Login | Register For Free | Help
Search for: (Advanced)

Mailing List Archive: exim: dev

Documentation: marking of expansion options in documentation

 

 

exim dev RSS feed   Index | Next | Previous | View Threaded


nigel at dotdot

Apr 12, 2012, 2:00 AM

Post #1 of 3 (314 views)
Permalink
Documentation: marking of expansion options in documentation

Theres been a couple of cases recently where people have been caught out
by whether a configuration option uses expanded string value or the
literal string.

Currently we mark whether or not an option expands its value by adding a
dagger symbol to the type - see the first couple of entries at

http://www.exim.org/exim-html-current/doc/html/spec_html/ch14.html#SECTalomo

Would it be sensible to see about changing that dagger to something else
- say the string " (expanded)" in a smaller font, to make things rather
more obvious to those glancing at the docs.

[.I'm also wondering about the idea of trying to grab a complete option
list from the source code and comparing it to that in the documentation,
but thats another ramble]

Nigel.

--
[ Nigel Metheringham ------------------------------ nigel [at] dotdot ]
[ Ellipsis Intangible Technologies ]


--
## List details at https://lists.exim.org/mailman/listinfo/exim-dev Exim details at http://www.exim.org/ ##


pdp at exim

Apr 12, 2012, 2:19 AM

Post #2 of 3 (306 views)
Permalink
Re: Documentation: marking of expansion options in documentation [In reply to]

On 2012-04-12 at 10:00 +0100, Nigel Metheringham wrote:
> Theres been a couple of cases recently where people have been caught out
> by whether a configuration option uses expanded string value or the
> literal string.
>
> Currently we mark whether or not an option expands its value by adding a
> dagger symbol to the type - see the first couple of entries at
>
> http://www.exim.org/exim-html-current/doc/html/spec_html/ch14.html#SECTalomo
>
> Would it be sensible to see about changing that dagger to something else
> - say the string " (expanded)" in a smaller font, to make things rather
> more obvious to those glancing at the docs.

As long as it's output format-specific, I'm okay with that. It just
won't fit in the plain text output.

Of course, at this point it might be worth instead explicitly marking
those options which are *not* expanded.

> [.I'm also wondering about the idea of trying to grab a complete option
> list from the source code and comparing it to that in the documentation,
> but thats another ramble]

I did a sweep a couple of releases ago, to make sure OptionLists.txt was
up-to-date; I don't recall if I cross-referenced the main docs

Expanded-or-not requires more investigation for every option. :/

-Phil

--
## List details at https://lists.exim.org/mailman/listinfo/exim-dev Exim details at http://www.exim.org/ ##


jgh at wizmail

Apr 12, 2012, 12:38 PM

Post #3 of 3 (300 views)
Permalink
Re: Documentation: marking of expansion options in documentation [In reply to]

On 2012-04-12 10:19, Phil Pennock wrote:
> On 2012-04-12 at 10:00 +0100, Nigel Metheringham wrote:
>> Would it be sensible to see about changing that dagger to something else
>> - say the string " (expanded)" in a smaller font, to make things rather
>> more obvious to those glancing at the docs.
>
> As long as it's output format-specific, I'm okay with that. It just
> won't fit in the plain text output.

+1

--
Jeremy

--
## List details at https://lists.exim.org/mailman/listinfo/exim-dev Exim details at http://www.exim.org/ ##

exim dev RSS feed   Index | Next | Previous | View Threaded
 
 


Interested in having your list archived? Contact Gossamer Threads
 
  Web Applications & Managed Hosting Powered by Gossamer Threads Inc.