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

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

On 22/06/2015 19:40, Corinna Vinschen wrote:
> On Jun 22 18:15, Jon TURNEY wrote:
>> 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>
>
> I missed something, apparently.  From where are these three referenced,
> but not the others?

> $ egrep -H 'xref linkend="ntsec-mapping-nsswitch-(home|shell|gecos|enum|pwdgrp)' ntsec.xml
> ntsec.xml:       See <xref linkend="ntsec-mapping-nsswitch-home"></xref>.</seg>
> ntsec.xml:       See <xref linkend="ntsec-mapping-nsswitch-shell"></xref>.</seg>
> ntsec.xml:       See <xref linkend="ntsec-mapping-nsswitch-gecos"></xref>.</seg>
> ntsec.xml:       See <xref linkend="ntsec-mapping-nsswitch-home"></xref>.</seg>
> ntsec.xml:       See <xref linkend="ntsec-mapping-nsswitch-shell"></xref>.</seg>
> ntsec.xml:       See <xref linkend="ntsec-mapping-nsswitch-gecos"></xref>.</seg>

It's seems to be a peculiarity of the .info format that a title with a 
':' in it is fine, but you can't make an xref to it without providing an 
alternate link text, as ':' terminates the link text

>> Even then, it's not consistent with the text, which always treats : as part
>> of the keyword.
>
> Yeah.  I'm not overly happy with this myself.  I didn't know how better
> I could make clear that the colon is part of the keyword.
>
> So, ok.  Please apply.  Maybe it makes sense to add texinfo-nodes for
> the others in the list above as well?  Just in case?

I think there are other titles elsewhere, which are also not the target 
of a xref.

A "warning: @ref cross-reference name should not contain `:'" is emitted 
where this problem exists.