Re: [PATCH 1/5] winsup/doc: Create info pages from cygwin documentation

[Jon TURNEY <jon.turney@dronecode.org.uk>]

On 22/06/2015 15:55, Corinna Vinschen wrote:
> On Jun 22 15:39, Jon TURNEY wrote:
>> v2:
>> Updated to use docbook2x-texi not docbook2texi, since source is now docbook XML.
>> Tweak DocBook XML so info directory entry has a description.
>>
>> v3:
>> Use a custom charmap to handle ®
>>
>> v4:
>> Proper build avoidance
>> texinfo node references may not contain ':', so provide alternate text for a few
>> xref targets
>>
>> 2015-06-22  Jon Turney  <jon.turney@dronecode.org.uk>
>>
>> 	* Makefile.in (install-info, cygwin-ug-net.info)
>> 	(cygwin-api.info): Add.
>> 	* cygwin-ug-net.xml: Add texinfo-node.
>> 	* cygwin-api.xml: Ditto.
>
> This is fine.
>
>> 	* ntsec.xml (db_home): Add texinfo-node for titles containing a
>> 	':' which are the targets of an xref.
>
> This... not so much.  Let's simply remove the colons instead:
>
> -<sect4 id="ntsec-mapping-nsswitch-home"><title id="ntsec-mapping-nsswitch-home.title">The <literal>db_home:</literal> setting</title>
> +<sect4 id="ntsec-mapping-nsswitch-home"><title id="ntsec-mapping-nsswitch-home.title">The <literal>db_home</literal> setting</title>
> [...]

I did consider this, but to be consistent it would needs to be removed 
from all section titles:

> <sect4 id="ntsec-mapping-nsswitch-pwdgrp"><title id="ntsec-mapping-nsswitch-pwdgrp.title">The <literal>passwd:</literal> and <literal>group:</literal> settings</title>
> <sect4 id="ntsec-mapping-nsswitch-enum"><title id="ntsec-mapping-nsswitch-enum.title">The <literal>db_enum:</literal> setting</title>
> <sect4 id="ntsec-mapping-nsswitch-home"><title id="ntsec-mapping-nsswitch-home.title">The <literal>db_home:</literal> setting</title>
> <sect4 id="ntsec-mapping-nsswitch-shell"><title id="ntsec-mapping-nsswitch-shell.title">The <literal>db_shell:</literal> setting</title>
> <sect4 id="ntsec-mapping-nsswitch-gecos"><title id="ntsec-mapping-nsswitch-gecos.title">The <literal>db_gecos:</literal> setting</title>

Even then, it's not consistent with the text, which always treats : as 
part of the keyword.