tech@mandoc.bsd.lv
 help / color / mirror / Atom feed
From: Ingo Schwarze <schwarze@usta.de>
To: "Anthony J. Bentley" <anthony@anjbe.name>
Cc: tech@mandoc.bsd.lv
Subject: Re: docbook2mdoc and [sub]section links
Date: Mon, 20 May 2019 19:45:06 +0200	[thread overview]
Message-ID: <20190520174506.GA53563@athene.usta.de> (raw)
In-Reply-To: <9061.1558331438@desktop.ajb.soy>

Hello Anthony,

Anthony J. Bentley wrote on Sun, May 19, 2019 at 11:50:38PM -0600:

> Instances of .Sx that docbook2mdoc(1) generates in text don't match the
> case of the actual section name. The Sx's printed text (and, in HTML
> output, the href of the hyperlink) will come from the section's id in
> the DocBook source, which is not correct.

Yes, this is a known shortcoming.  The proper fix involves:

 1. During parsing, building a table of ID attributes.
 2. During parsing, record the <xref> (and possibly similar)
    attributes as-is.
 3. In a later validation phase (after parsing), iterate all
    nodes an change those pointing to ID attributes to point
    the titles associated with the ID attributes.

So far, i shied away from doing that because it is slightly complex.
But it needs to be done at some point.

> A related problem is with <sect3>. docbook2mdoc(1) generates Sy in Pp
> for the tag. While dissatisfying, I don't know what better solution
> there could be at the moment. But since this can't be treated as a
> normal section cross reference, docbook2mdoc(1) should not create Sx
> for references to <sect3>.

Thanks, i wasn't aware of that aspect yet.

You are right that mdoc(7) simply doesn't support a third level of
sections - which is more a feature than a bug, avoiding excessive
complexity of documentation.

I agree that in such a situation docbook2mdoc(1) should just not
generate the .Sx macro.  That requires selectively adding entries
to the ID table, then deleting cross references during the validation
phase when there is no match for the target.

This is all a bit on the more tedious, lower priority side of
features to implement, yet it should clearly be done.

Yours,
  Ingo
--
 To unsubscribe send an email to tech+unsubscribe@mandoc.bsd.lv

      reply	other threads:[~2019-05-20 17:45 UTC|newest]

Thread overview: 2+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-05-20  5:50 Anthony J. Bentley
2019-05-20 17:45 ` Ingo Schwarze [this message]

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=20190520174506.GA53563@athene.usta.de \
    --to=schwarze@usta.de \
    --cc=anthony@anjbe.name \
    --cc=tech@mandoc.bsd.lv \
    --subject='Re: docbook2mdoc and [sub]section links' \
    /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).