Feedback on doc lang changes

[dbuenzli]

No description provided.

[gasche]

The choice of escaping ) as )) struck me as a bit surprising. Is it standard in other languages with $(...) quotes? In particular, the effect it has on $(foo,$(bar)) seems unfortunate.

[ivg]

I personally find )) escaping slightly odd and moderately fragile. First of all, it is not a well-known way to escape a parenthesis. Second, I foresee lots of troubles, as multiple closing parentheses is a common pattern in programming documentation, e.g., $(b, Error (Error.of_string "failure")).

My suggestion would be to use a regular backslash escaping (probably it should be used for $ escaping also) or some kind of quoting.

Require a quoting to introduce verbatim strings. It can be as simple as using double or single quotes (with all expected caveats), or something similar to latex verbatim macro, e.g., $verb|...|. I would vote for the quoting, cf. how parenthesis are escaped in the sexp library. If a string atom contains any special symbols, then it should be just delimited with quotes, and any occurring quote should be escaped. The mechanism is pretty easy to implement and to understand.

[dbuenzli]

The choice of escaping ) as )) struck me as a bit surprising. Is it standard in other languages with $(...) quotes?

I don't know, for me the standard is really backslashes, but given the context in which this is written (OCaml strings) backslash escapes are annoying to write.

I understand the concerns but OTOH I'm not sure @ivg's example is really compelling. These bold and italics directives are unlikely to be used beyond short strings for (meta-)variables and options and IMHO certainly not for code snippets. So introducing a lot of machinery for that seems a bit overkill.

[nojb]

Regarding the slashes, this is helped by {|...|}, but of course this is only present in recent versions of OCaml...

[dbuenzli]

@nojb good point.

[ivg]

@dbuenzli, according to man man-pages the boldface is used for as-is text and italics are used to indicate replaceable arguments. Basically, the $(b,xxxx) is a code escaping sequence the same as backticks in github markup. So, whenever I'm writing a synopsis or code examples, I should delimit them with the bold markup, e.g., $(b, print_tuple (x,y)) prints a tuple.

Moreover, according to the man man-pages we even need to nest b and i formatting:

For functions, the arguments are always specified using italics, even in the SYNOPSIS section, where the rest of the function is specified in bold

So we need to write $(b, int myfunction(int $(i,argc), char **$(i,argv)) to conform with the the man-pages standard, or, speaking OCaml $(b, print_tuple ($(i,x),$(i,y))).

The examples, that I show are synthetic of course, but in our code base, we have hundreds of real examples (in more than 50 man pages, generated by cmdliner), that now do not have any clear resolution. The worst-case scenario is man-page that documents a lisp-like DSP, that, believe me, has lots of parentheses)).

[dbuenzli]

$(b, print_tuple ($(i,x),$(i,y))).

Note that you couldn't do that before either. You'd have to write (with the current proposal):

$(b,print tuple ()$(i,x)$(b,,)$(i,y)$(b,)))

and I won't change this.

However if everyone prefers to have \$ (i.e. "\\$" in OCaml) for '$' everywhere and \) (i.e. "\\)" in OCaml for right parens ')' in $({i,b},_) directives then I'll implement this.

[dbuenzli]

and \\ (i.e. "\\\\" in OCaml) for '\' with any other sequence starting with a backslash being illegal.

[dbuenzli]

A failure in my code base finally convinced me that "))" is unnatural so I'll switch to backslash escapes everywhere.

Invalid_argument("Malformed $(...) in \"The configuration to act on (value of $(b,w.conf)).\"")

[ivg]

and I won't change this.

Yeah, sure, I was just dreaming. In any case, this will not break our existing code.

And I'm totally fine with the backslashes, as usually, we're writing manpages inside the {| |} literal.

[dbuenzli]

Thanks everyone. I implemented the better proposal. See the changes and/or docs

https://github.com/dbuenzli/cmdliner/blob/d325de4febd04250a376331e141dbc4154a84789/CHANGES.md#doc-language-sanitization

cmdliner/src/cmdliner.mli

Lines 755 to 772 in d325de4

	{2:doclang Documentation markup language}
	Block and doc strings support the following markup language.
	{ul
	{- Markup directives [$(i,text)] and [$(b,text)], where [text] is
	raw text respectively rendered in italics and bold.}
	{- Outside markup directives, context dependent variables of the
	form [$(var)] are substituted by marked up data. For example in a
	term's manpage [$(tname)] is substituted by the term name in bold.}
	{- Characters $, (, ) and \ can respectively be escaped by \$,
	\(, \) and \\ (in OCaml strings this will be ["\\$"], ["\\("], ["\\)"],
	["\\\\"]). Escaping $ and \ is mandatory everywhere. Escaping ) is
	mandatory only in markup directives. Escaping ( is only here for your
	symmetric pleasure. Any other sequence of characters starting with
	a \ is an illegal character sequence.}
	{- Refering to unknown markup directives or variables is a hard failure;
	[Invalid_argument] is raised.}}

[dbuenzli]

I'd like to add a directive for hyperlinks (#72). Here's the proposed syntax:

$(h,link linked text)

(The first token defines the hyper link the rest the linked text)

[dbuenzli]

The discussion in this issue may also be of interest.

[dbuenzli]

I'll close this. I think the main points have been addressed. Do not hesitate to open new issues or interact on the others mentioned. Thanks all for preventing me to add more nonsense to this broken language.