[krbdev.mit.edu #7187] ReST html docs render '--' as &#8211 (en dash)

[Benjamin Kaduk via RT]

On Sat, 30 Jun 2012, Zhanna Tsitkova via RT wrote:

> [kaduk at 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 &#8211.
>> 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