Re: Formatting of options.

[Bastiaan Veelo]

Peter,

Peter Simons wrote:

> Bastiaan Veelo writes:
>
> >> dnl Options:
> >> dnl
> >> dnl --with-Qt-dir=DIR: DIR is equal to $QTDIR if you
> >> dnl have followed the installation instructions of
> >> dnl Trolltech. Header files are in DIR/include, binary
> >> dnl utilities are in DIR/bin and the library is in
> >> dnl DIR/lib.
> >> dnl
> >> dnl --with-Qt-include-dir=DIR: Qt header files are in
> >> dnl DIR.
>
> One approach I could imagine would be to define a special
> type of ':' which has special semantics. Let's use '::=' for
> an example. You would write:
>
>  dnl --with-Qt-dir=DIR ::= DIR is equal to $QTDIR if you
>  dnl have followed the installation instructions of [...].
>  dnl
>
> Then the software would know that "--with-Qt-dir=DIR" is a
> term, and that all following text until the next empty line
> is its explanation. In HTML, this could be marked up as a
> <dl> definition list.
>  

You may be right that ::= is more robust, if you care for generated HTML 
only. However, for me readability in the source is just as important, 
and "::=" is strange and confusing, IMHO. I would say either use ":" or 
leave things as they are.

> A slight variation, which looks nicer in plain text, would
> be:
>
>  dnl --with-Qt-dir=DIR ::= DIR is equal to $QTDIR if you
>  dnl   have followed the installation instructions of
>  dnl   Trolltech. [...]
>  dnl normal text or next item or empty line
>
> Here, a multi-line explanation would have to be indented. An
> empty line could follow, but would have no significance.
> Like I said, the only difference is that this one seems to
> look neater, technically the two schemes are equivalent.
>  

Personally I prefer the first variant, termination by en empty line, 
because it is faster than indenting every line, and it has no 
consequences if the text is edited. Besides, I would insert an empty 
line anyway to better mark the beginning and end of each option. I agree 
that indenting looks nice though, and in the first variant indenting is 
optional.

Regards,
Bastiaan.