[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [docbook-apps] Refentry, man pages, and DocBook XSL 1.69.0
Hi Peter, You wrote: > Thanks for alerting me to this update. We have been authoring > our man pages in DocBook XML here at Cray for over 4 years Great to hear that. I've added a note to the WhoUsesDocBook page at the DocBook Wiki - http://wiki.docbook.org/topic/WhoUsesDocBook (I hope that's not a problem. If it is, please let me know and I will remove it or edit it in any way you want.) [...] > That said, for now we'll continue to use the docbook-to-man package for > *roff conversion, though I'll be using XSL for HTML conversion. > docbook-to-man (originally by Fred Dalrymple and now under the Debian > umbrella) is 3-4x faster than the XSL, and provides the same functionality. > I've modified the Debian version to work with XML (originally it was SGML > only). I have not used docbook-to-man much. I know it's way faster than the docbook-xsl manpages stylesheet. (I'll reply about the speed issue in another message.) But I'd question whether it provides the same functionality. There are a great many things that the manpages stylesheet does[1] that docbook-to-man doesn't, or even can't do (at least based on what I know about it). And I would guess that in order to get usable output from docbook-to-man, you might be constraining yourself and your authors to a subset of elements, not the complete set of elements that DocBook says are valid in Refentry. For example, can your authors use Xref and Ulink in documents destined for man-page output? Can they use Footnote? Are there any elements that your authoring guidelines are telling them to specifically avoid because they cannot be processed by docbook-to-man? --Mike [1]I think that docbook-to-man supports conversion of DocBook tables, which the manpages XSL stylesheet does not yet. But there are a few other things that the manpages stylesheet does that, as far as I know, docbook-to-man does not. - Synopsis handling. Below is an example of a synopsis in a man page generated using the manpages stylesheet. clisp [[-h] [--help]] [--version] [--license] [-B lisp-lib-dir] [-K linking-set] [-M mem-file] [-m mem-size] [-t temp-dir] [-L language] [-N locale-dir] [-Edomain encoding] [[-q] [--quiet] [--silent] [-v] [--verbose]] [-on-error action] [-repl] [-w] [-I] [[-ansi] [-traditional]] [-modern] [-p package] [-C] [-norc] [-i init-file...] [-c [-l] lisp-file [-o output-file]...] [-x expressions...] [lisp-file [argument...]] And below is the synopsis in the same man page when I set my MANWIDTH to 65. clisp [[-h] [--help]] [--version] [--license] [-B lisp-lib-dir] [-K linking-set] [-M mem-file] [-m mem-size] [-t temp-dir] [-L language] [-N locale-dir] [-Edomain encoding] [[-q] [--quiet] [--silent] [-v] [--verbose]] [-on-error action] [-repl] [-w] [-I] [[-ansi] [-traditional]] [-modern] [-p package] [-C] [-norc] [-i init-file...] [-c [-l] lisp-file [-o output-file]...] [-x expressions...] [lisp-file [argument...]] The manpages stylesheet automatically creates a hanging indent of the correct width and keeps the arguments together in such a way that they are not broken across lines. As far as I know, docbook-to-man can't do that, and no other Refentry-to-man system can either. - Handling of documents containing multiple Refentry instances. docbook-to-man is a filter that writes its output to standard out. The manpages stylesheet automatically generates files, with extensions based on the Manvolnum it finds for each Refentry. And if a document contains multiple Refentry instances, it automatically generates a separate man-page output file for each. I think a lot of users would consider those two features to be fundamental requirements of a usable Refentry-to-man system. (And for the record, they were features in the manpages stylesheet since long before I ever touched or even looked at the code myself, so I can't take credit for them). I have also recently added support for, or am planning to add support for, some things that weren't supported correctly before: - Xref. Display of contents of Xref is now handled in exactly the same way as the HTML stylesheets handle it, except no hyperlink is generated. That is, if you put in an Xref to another Section in a document, the title of that Section is picked up and used as the output for the Xref. - Links. Because there is no way in man-page output to generated real hyperlinks, I added a mechanism for listing URLs for all links at the end of the man page, and optionally numbering each link and generating a matching number in the link list. - Footnotes. I am planning to handle Footnote similar to the way that links are handled. Currently the manpages stylesheet correctly generates a Footnote number, but does nothing with the actual Footnote content. - Tables. This one will be some work, but it is not such a big technical challenge. I just need to time to get it done.
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]