tech@mandoc.bsd.lv
 help / color / mirror / Atom feed
From: Stephen Gregoratto <dev@sgregoratto.me>
To: tech@mandoc.bsd.lv
Subject: Re: [PATCH docbook2mdoc] Add NODE_EMAIL
Date: Sat, 23 Mar 2019 16:30:08 +1100	[thread overview]
Message-ID: <20190323053008.vctluoysjwtc3usv@BlackBox> (raw)
In-Reply-To: <20190322200700.GD6535@athene.usta.de>

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] 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].
 
> 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 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 ;).

Also, I do like using mdoc and mandoc and thought I could help out with
the DocBook converter. 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 rebased your patch such that it applied to HEAD and committed it
> in the following form.
> 
> Test results:
>    $ cat tmp.txt
>   <author>
>     <personname>
>       <firstname>Joe</firstname>
>       <othername>Bloggo</othername>
>       <surname>Bloggs</surname>
>     </personname>
>     <email>joe@foo.net</email>
>   </author>
>    $ ./docbook2mdoc tmp.txt | man -lc
> UNKNOWN(1)                  General Commands Manual                 UNKNOWN(1)
> 
> Joe Bloggo Bloggs <joe@foo.net>
> 
> OpenBSD 6.4                     March 22, 2019                     OpenBSD 6.4

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.? For now I'll put my <author> node in its own
<refsect>.

[1] https://gitlab.com/esr/doclifter/raw/master/doclifter.xml
[2] https://gitlab.gnome.org/GNOME/gtk/raw/master/docs/reference/gtk/gtk4-launch.xml
[3] https://gitlab.gnome.org/GNOME/gtk/blob/master/docs/reference/gtk/css-overview.xml#L510
-- 
Stephen Gregoratto
PGP: 3FC6 3D0E 2801 C348 1C44 2D34 A80C 0F8E 8BAB EC8B
--
 To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv

  reply	other threads:[~2019-03-23  5:30 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 [this message]
2019-03-23  8:46     ` Ingo Schwarze
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=20190323053008.vctluoysjwtc3usv@BlackBox \
    --to=dev@sgregoratto.me \
    --cc=tech@mandoc.bsd.lv \
    /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
Be sure your reply has a Subject: header at the top and a blank line before the message body.
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).