From: Ingo Schwarze <email@example.com> To: Stephen Gregoratto <firstname.lastname@example.org> Cc: email@example.com Subject: Re: [PATCH docbook2mdoc] Add NODE_EMAIL Date: Sat, 23 Mar 2019 09:46:16 +0100 [thread overview] Message-ID: <20190323084616.GA62193@athene.usta.de> (raw) In-Reply-To: <20190323053008.vctluoysjwtc3usv@BlackBox> Hi Stephen, Stephen Gregoratto wrote on Sat, Mar 23, 2019 at 04:30:08PM +1100: > On 2019-03-22 21:07, Ingo Schwarze wrote: >> In the future, it might be useful to mention in which real-world >> document(s) you found a given feature used. > The manpages for doclifter/manlifter Oh. That package is definitely important. > contain esr's email address enclosed in an <email> node. > I've also come across the <author> block in the GNOME project's > GTK docs. > > The big DocBook users are the FreeDesktop group and it's members: GNOME, > KDE, Systemd et al. If we work through the smaller cases (like GTK's), > we can eventually start thinking about how to transform longer and more > complicated ones. Case in point, this section I found in the GTK > docs. All that makes a lot of sense to me. Thanks for explaining. >> Thank you, help working on docbook2mdoc(1) is certainly welcome! >> Just out of curiosity: What are you using docbook2mdoc(1) for? > I've interacted with many manpage generators so far, so I thought I'd > make a good faith comparison between the many I've seen/used in OSS. > I've decided I'd start with the generators I know the least, which are > refentry files. I can't say i have ever *used* the DocBook format, but the man(7) output from DocBook files has struck me over and over again as the by far lowest quality man(7) code i have ever seen from any manual page generator. DocBook is without any doubt the number one manual page generation scheme causing the most trouble in real life, in multiple respects. By far. So i am definitely not able to approach DocBook in good faith; i strongly hate DocBook and i am heavily biased against it based on previous experience. But our different perspective on it can likely be productive. :) > I was going to compare docbook2mdoc's output to the official XSL > stylesheets to see how they compare, But I can't compare them if > it exits on an unseen node ;). Right. Even though docbook2mdoc(1) is now five years old, it is still clearly experimental software in an early stage of development. The version number 0.0.9 makes sense in that respect. > Also, I do like using mdoc and mandoc and thought I could help out > with the DocBook converter. Good, thanks. I see at least three reasons why that might be useful: 1. Some parts of X11 documentation currently exist in DocBook form. Short term, it is useful to convert them to mdoc(7) and install them as part of Xenocara in OpenBSD. 2. Medium term, it might be an option to use docbook2mdoc(1) for building the documentation of (at least some) ports having DocBook documentation. That is, run docbook2mdoc(1) at port build time and let the pkg install the resulting mdoc(7) files. Not sure yet how well that may work, but if it does, it would give users higher quality documentation, allowing semantic search in particular, better HTML output, and even better man(1) terminal output that better matches usual conventions. 3. Long term, it might be possible to build a toolchain out of doclifter(1) and docbook2mdoc(1) to convert legacy man(7) manual pages to mdoc(7). Not sure yet how well that may work. > My personal goal is to convert most of the systemd manpages, > as they contain many tables/code listings that would > look good when going through mandoc's HTML output. I see. Even though systemd is not software that could reasonably be ported to OpenBSD, i see your point. > Cheers. Something I noticed is that many documents put the authors in > the <refmeta> section, which the XSL stylesheets move into AUTHORS. Not > sure how we would deal with this. Perhaps a string buffer or array of > struct author that could be printed out at the end/before > CAVEATS/BUGS et al.? The canonical approach would be to use the syntax tree itself to store the information and let the formatter decide what needs to be printed at which time. Usually, the formatter formats elements in tree order, but it can (and already does) print some out of order, earlier (or for AUTHORS, it would be later). That implies skipping the nodes when the normal tree walk comes across them and explicitely accessing them from the place where they have to be printed. Another idea might be to insert a validation stage which could, among other transformations, do reordering before starting the tree walk for formatting. Not sure yet whether that is a good idea - it may be useful, even needed at some point, or it may turn out to be overengineering... > For now I'll put my <author> node in its own <refsect>. I'm not sure i understand that sentence. What do you mean with "I'll put"? Aren't DocBook elements part of input documents, and aren't input documents things that are given a priori? How can you influence what is found in input documents? Yours, Ingo -- To unsubscribe send an email to firstname.lastname@example.org
next prev parent reply other threads:[~2019-03-23 8:46 UTC|newest] Thread overview: 7+ messages / expand[flat|nested] mbox.gz Atom feed top 2019-03-22 10:33 Stephen Gregoratto 2019-03-22 12:32 ` Ingo Schwarze 2019-03-22 20:07 ` Ingo Schwarze 2019-03-23 5:30 ` Stephen Gregoratto 2019-03-23 8:46 ` Ingo Schwarze [this message] 2019-03-23 10:18 ` Stephen Gregoratto 2019-04-25 18:33 ` Ingo Schwarze
Reply instructions: You may reply publicly to this message via plain-text email using any one of the following methods: * Save the following mbox file, import it into your mail client, and reply-to-all from there: mbox Avoid top-posting and favor interleaved quoting: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --in-reply-to=20190323084616.GA62193@athene.usta.de \ --email@example.com \ --firstname.lastname@example.org \ --email@example.com \ --subject='Re: [PATCH docbook2mdoc] Add NODE_EMAIL' \ /path/to/YOUR_REPLY https://kernel.org/pub/software/scm/git/docs/git-send-email.html * If your mail client supports setting the In-Reply-To header via mailto: links, try the mailto: link
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).