tech@mandoc.bsd.lv
 help / color / mirror / Atom feed
From: Ingo Schwarze <schwarze@usta.de>
To: Stephen Gregoratto <dev@sgregoratto.me>
Cc: tech@mandoc.bsd.lv
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[1]

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[2].
> 
> 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[3].

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 tech+unsubscribe@mandoc.bsd.lv

  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 \
    --to=schwarze@usta.de \
    --cc=dev@sgregoratto.me \
    --cc=tech@mandoc.bsd.lv \
    --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).