[PATCH v2] winsup/doc/posix.xml: add note for getrlimit, setrlimit, xrefs to notes

[Brian Inglis]

On 2021-02-17 02:29, Corinna Vinschen via Cygwin-patches wrote:
> On Feb 16 10:00, Brian Inglis wrote:
>> On 2021-02-16 09:51, Brian Inglis wrote:
>>> On 2021-02-16 04:30, Corinna Vinschen via Cygwin-patches wrote:
>>>> On Feb 15 15:35, Brian Inglis wrote:
>>>>> change notes to see "Implementation Notes" to xref to std-notes;
>>>>> add xref to std-notes to getrlimit, setrlimit;
>>>>> add note to document limitations of getrlimit, setrlimit resources support
>>>>> ---
>>>>>    winsup/doc/posix.xml | 101 ++++++++++++++++++++++++-------------------
>>>>>    1 file changed, 57 insertions(+), 44 deletions(-)
>>>
>>>> Pushed with a change:
>>>>     <xref linkend="std-notes">(see chapter "Implementation Notes")</xref>
>>>> -->
>>>>     (see <xref linkend="std-notes">chapter "Implementation Notes"</xref>)
>>>> The reason is how xref is handled when creating html docs.  The result
>>>> of an xref is always 'the section called "..."'.  With the above change,
>>>> the text works (albeit differently) in html and info file.
>>>
>>> Cheers, thanks, I'll bear that in mind in future, and read the generated
>>> output more carefully.
>>>
>>> I'm not seeing .info generated with Note:... links, is that okay?
> 
> db2x_docbook2texi from docbook2X is used for that.

Cygwin provides db2x_texixml in docbook2X 0.8.8

>>> Also ...api.pdf is no longer being regenerated, so what have I lost or am missing?
> 
> xmlto is doing this stuff, maybe the pdf option requires another package?

I thought that was dblatex via TeX and/or poppler

>>> I have the following doc tools (and others):
>>>
>>> $ apt l asciidoc dblatex poppler\$ xmlto
>>> asciidoc 8.6.9-1 x86_64 [installed, manual]
>>> dblatex 0.3.10-1 x86_64 [installed, automatic]
>>> poppler 21.01.0-1 x86_64 [installed, manual]
>>> xmlto 0.0.28-1 x86_64 [installed, automatic]
>>
>> Also as documented plus other dependencies:
>>
>> $ apt l build-docbook-catalog docbook-sgml45 docbook-utils docbook-xml45 \
>> 	docbook-xsl docbook2X
>> build-docbook-catalog 1.5-2 x86_64 [installed, automatic]
>> docbook-sgml45 4.5-1 x86_64 [installed, automatic]
>> docbook-utils 0.6.14-2 x86_64 [installed, manual]
>> docbook-xml45 4.5-1 x86_64 [installed, manual]
>> docbook-xsl 1.77.1-1 x86_64 [installed, automatic]
>> docbook2X 0.8.8-1 x86_64 [installed, manual]
>>
>>> What else is needed?
> 
> Good question.  I'm running that on Fedora with the following docbook
> packages installed:
> 
>    docbook-dtds
>    docbook-style-xsl
>    docbook-style-dsssl
>    docbook-utils
>    docbook2X

Also got docbook-dsssl and all but docbook-xsl-ns - will install that

> xmlto adds a dependency to flex.  docbook2X depends on texinfo, texinfo
> comes with a number of packages on the far side of infinity.

Got bison, byacc, and flex; texinfo requires only a few std libs and perl 
modules, it's not La/TeX.

> Jon?  Any idea?

Last cygwin-api.pdf generated was 2020 Nov 10, last cygwin-ug-net.pdf generated 
was 2020 Dec 17.

Missed error ignored by build:

...
xmlto --skip-validation --with-dblatex pdf -o cygwin-api/ -m 
../../../../winsup/doc/fo.xsl ../../../../winsup/doc/cygwin-api.xml
Traceback (most recent call last):
   File "/usr/bin/dblatex", line 10, in <module>
     from dbtexmf.dblatex import dblatex
ModuleNotFoundError: No module named 'dbtexmf'
make[3]: [Makefile:128: cygwin-api/cygwin-api.pdf] Error 1 (ignored)
...

Looks like it was installed by dblatex in python2.7/site-packages which I wiped 
when I dropped python2 et. al. and upgraded to python3. Oops - my bad!

$ cygcheck -c dblatex
Cygwin Package Information
Package              Version        Status
dblatex              0.3.10-1       Incomplete

Thanks for help and sorry for wasting time.
I need to upgrade anyway as there is a backlog of 187 packages waiting for me to 
download 84MB including dblatex and python3!

-- 
Take care. Thanks, Brian Inglis, Calgary, Alberta, Canada

This email may be disturbing to some readers as it contains
too much technical detail. Reader discretion is advised.
[Data in binary units and prefixes, physical quantities in SI.]