On Sat, 30 Jun 2012, Zhanna Tsitkova via RT wrote:
Show quoted text
> [kaduk@MIT.EDU - Fri Jun 29 15:57:26 2012]:
>
>> We use '--' for the long form of command arguments in a few places in
>> the doc tree, most notably in krb_build/options2configure.rst .
>> When rendered into html (other formats are not checked and also
>> potentially problematic), the '--' becomes an en dash character,
>> represented in the html source as –.
>> Since we are documenting the actual configure options, which use two
>> ASCII 055 characters (not a unicode en dash), we should have our
>> rendered documentation produce that output.
>>
>> I forget whether it was Greg or Tom who pondered whether these arguments
>> should be in `` blocks anyway.
>> The sphinx/ReST documentation I've looked at so far does not make it
>> clear whether this conversion behavior is configurable.
>
> Enabled SmartyPants in the Sphinx config file is responsible for this
> behavior.
Thanks for the reference.
It seems that we are not correctly using the SmartyPants dash-correction
feature anywhere in our reST documentation; the string '---' appears only
in underline/line drawing regions. We do have '--' used in a few places
other than configure options:
krb_admins/conf_files/krb5_conf.rst
krb_appldev/init_creds.rst
krb_users/pwd_mgmt.rst
krb_users/pwd_mgmt.rst
where it is used to indicate an em dash (but SmartyPants translates it to
an en dash).
krb_users/tkt_mgmt.rst
uses '--' a handful of times for arrow-drawing in quoted literal context.
However, SmartyPants provides "education" (their phrase) for quotes as
well as dashes, and there does not appear to be a configuration option to
only apply one set of transformations and not both, so we would need to
consider those effects as part of any consideration of disabling
SmartyPants. I did not do an exhaustive survey of our use of SmartyPants'
quote-education feature, but I did find a few places it affects through
spot-checking.
reST does provide a built-in functionality to describe (command-line)
option lists, such as our lists of configure options in
krb_build/options2configure.rst . I have played around with this
somewhat, and it does not appear to be directly suitable for us, since it
does not support options with optional parameters (e.g., "--with-netlib
[=libs]") -- the only allowed forms for arguments are as follows:
%%%%%%%%%%%%%%%%
Option arguments may take one of two forms:
. Begins with a letter ([a-zA-Z]) and subsequently consists of letters,
numbers, underscores and hyphens ([a-zA-Z0-9_-]).
. Begins with an open-angle-bracket (<) and ends with a
close-angle-bracket (>); any characters except angle brackets are
allowed internally.
%%%%%%%%%%%%%%%
Furthermore, the indentation of the option description behaves poorly for
our particular option list -- "--help" is first, and has the description
begin on the same line as the option, but the subsequent options are
longer and so the description begins on a new line. This could probably
be tweaked using CSS, but I think would affect other places as well.
If we elect to continue manually formatting the options, putting them in a
quoted literal context provides the same sort of formatting as the
built-in option list framework. However, it does not seem possible to get
bold quoted-literal text at all, so we would sacrifice our convention of
using boldface for options, in this listing.
It's really not clear to me which course of action will produce the best
overall result; the choices seem to fit into categories of:
(1) disable SmartyPants and lose on smart quotes (or input the Unicode for
them manually)
(2) Use the reST options list framework and hack around the parts that
don't work
(3) Continue manually formatting
(3a) using quoted literals to avoid spurious dash entities
(3b) using boldface text as we presently do
More opinions are welcome.
-Ben
