See bug #63042 for an attempted resurrection of this issue.

Hello again (yes it's Steffen),

this is not about the second iteration but two real bugs have been found in the  meanwhile and since i really enjoy mdocmx(7) i'm eager for posting the fixes.  Sorry for the noise :)

Two bugs in the preprocessor:

. for one processing an already preprocessed document didn't work, a bug that has been introduced when output device specifications for ".Mx -enable" had been added.

. second, creating the temporary file has at some time be changed to the colon : shell special built-in command, but shells have to hard exit once such a command fails, therefore it was an error to keep {;} and not encapsulate in a subshell.

. remove some redundancy in shell traps.

And then the groTTY output now prints references in blue.  This seems to have become common on GNU/Linux, and not being very hip causes hops.

More hopefully for christmas.  Ciao.

(file #35046)

Ingo's #9:

> Bad idea. Don't use macros in header lines.

Hm, tja, na ja...

>> For now i think it is absolutely sufficient to state --
>> for mdocmx -- that people should use a headline like
>> "Device daemon events" as the headline, especially since
>> the next output line contains the same reference again.

> Exactly, and not just for mdocmx, but for mdoc(7) in general,
> and not just for now, but for good. I should probably add
> a warning message to mandoc(1) to be printed when people
> make the mistake of putting macros into header lines.

..it seems some people want to do so and we have to deal with that!

> In the context of mdocmx, i don't think you need to worry
> about such craziness at all.

You know, i like it and i don't consider this dead!
For the current release of the MUA i maintain i have spend the time necessary to fix at least the worst misgenerations of grohtml(1) and placed a mdocmx(7)ified version of its manual on the web [1], and there you can see in action mdoc(7) effectively doing great when .Mx anchors are used!
And i personally like it even more on the terminal and in less(1), since then the .Xr references also work.

 [1] http://sdaoden.users.sourceforge.net/code-nail.html

But in the meanwhile i looked around a bit and the worst cases of .S[hs] i have found look like the following:

-----------
Source:

.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'

.Sh DESCRIPTION
.Ss Dq Blabla
.Ss "\s-1OPTIONS\s0"
.Ss "Options Controlling \*(C+ Dialect"
.Ss "Using \fBgcov\fP with \s-1GCC\s0 Optimization"
.Ss "Extension based on \fI.h\fP and \fI.c\fP files"
.Ss "Fixed parsing of $$<digit>, &$<digit>, etc."
.Ss "\-s, \-\-shuffle"
.Ss "new ( [\s-1OPTIONS\s0] )
.Ss "report Bundle|Distribution|Module"
.Ss "upgrade [Module|/Regex/]..."
.Ss "_search_module_tree( type => \s-1TYPE\s0, allow => \e@regexex, [data => \e@previous_results ] )"
.
Provide a bus- and machine-independent
.Dq DMA mapping interface .

-----------
mandoc(1):

DESCRIPTION
   “Blabla”

   OPTIONS

   Options Controlling C++ Dialect

   Using gcov with GCC Optimization

   Extension based on .h and .c files

   Fixed parsing of $$<digit>, &$<digit>, etc.

   -s, --shuffle

   new ( [OPTIONS] )

   report Bundle|Distribution|Module

   upgrade [Module|/Regex/]...

   _search_module_tree( type => TYPE, allow => \@regexex, [data =>
   \@previous_results ] )
     Provide a bus- and machine-independent “DMA mapping interface”.

-----------
groff(1) with mdocmx(7) (debug mode):

(TOC):
     DESCRIPTION[4]
           Dq Blabla[11]
           OPTIONS[12]
           Options Controlling C++ Dialect[13]
           Using gcov with GCC Optimization[14]
           Extension based on .h and .c files[15]
           Fixed parsing of $$<digit>, &$<digit>, etc.[16]
           -s, --shuffle[17]
           new ( [OPTIONS] )[18]
           report Bundle|Distribution|Module[19]
           upgrade [Module|/Regex/]...[20]
           _search_module_tree( type => TYPE, allow => \@regexex, [data =>
                             \@previous_results ] )[21]

DESCRIPTION@4@[4]
   @11@[11]“Blabla”
   OPTIONS@12@[12]
   Options Controlling C++ Dialect@13@[13]
   Using gcov with GCC Optimization@14@[14]
   Extension based on .h and .c files@15@[15]
   Fixed parsing of $$<digit>, &$<digit>, etc.@16@[16]
   -s, --shuffle@17@[17]
   new ( [OPTIONS] )@18@[18]
   report Bundle|Distribution|Module@19@[19]
   upgrade [Module|/Regex/]...@20@[20]
   _search_module_tree( type => TYPE, allow => \@regexex, [data =>
     \@previous_results ] )@21@[21]
     Provide a bus- and machine-independent “DMA mapping interface”.

-----------
So mdocmx would be capable to deal with all of that, except that mdoc(7) resolves "Dq BlaBla" by recursing, and we cannot do nothing about that unless mdoc(7) is rewritten the way i imagined.
Until then i will implement (debug) warnings shall we detect macros (we know about).
I think that is all that can be done.
I'll post the updated macros / preprocessor / manuals then.  (After S-roff is building.)

For your interest: today i have seen a case were mdocmx fails.

FreeBSD commit r284611 (Xin LI):
share/man/man4/acpi_ibm.4:

-.Ss Xr devd 8 Ss Events
+.Ss Xr devd 8 Events
 Hotkey events received by
 .Xr devd 8
 provide the following information:

We resolve this as

  .Mx -anchor-spass Ss "Xr devd 8 Events" 4

which (in debug mode) ends up as

  @11@[11]devd(8) Events[35]

(instead of "devd(8)[35] Events@11@[11]").
[35] is the (correct) external manual reference devd(8)!

In fact i don't understand why we are able to resolve this at all, i'll inspect that once S-roff is usable.
My current plan would be to provide debug logs for the preprocessor and i don't know yet what i can do in mdocmx(7) in order to warn the user.
Can this ever work correctly in non-multipass troff(1) and without rewriting mdoc(7) as imagined?  I don't know yet.
Like i've said, i'm wondering why we are able to provide correct anchor and links as such.
For now i think it is absolutely sufficient to state -- for mdocmx -- that people should use a headline like "Device daemon events" as the headline, especially since the next output line contains the same reference again.

Final note, since some manuals, including GNU roff ones, sometimes use .Xr without a reference: if the manual would have been changed to

 .Ss Xr devd Events

we would have got

 @11@[11]devd(Events)[35]

(or "devd(Events)" in mandoc(1)), so that i truly see the use case as above as an error.

ah - and i wonder what could be done to support those .Xr external references in an output format like, especially, PDF: i think i'll also add a ".if d MACRO" to optionally build an URL?  I see your program does support .Xr, being able to specify a target.
Thanks again!

The nail.pdf looks quite similar to this:-

http://chuzzlewit.co.uk:8080/cgi-bin/WebManPDF.pl/man:/nail

Which is a program which converts man pages, of all types - not just mdoc, to pdf format. I do prefer having the "Contents" section in the links panel, rather than the top of the page.

"Significant simplification"?
"Completely unstable"?
"Purely experimental"?

NONE of these are true!
Where did you get ANY evidence that back your words?
I have extended the following manuals with mdocmx(7):

- mdocmx.7, mdocmx.1.  Small and simple.

- nail.1: this is a VERY large and complicated manual page with multiple hundreds of anchors and references.  (As is it is shipped with ArchLinux (and CRUX Linux and Void Linux) in a preprocessed state and can thus be viewed in the wild if you only patch mdoc(7), grotty(1) and less(1).  With or without TOC, just the way you desire.  It can also be viewed if you don't patch them, but then without references and possible TOC.  Hallelujah.)

- mdoc(7) of S-roff.  Also a VERY large and complicated manual with hundreds of anchors and references.

- NetBSDs bus_dma.9 (C interface).  ~27000 bytes.

There is no evidence of just any problem!
Should anyone find any problem i'll fix them, of course.
Just see HOW simple the patches for grotty(1), less(1), mdoc(7) actually are!
Sorry for rising the voice somewhat.

Maybe -- maybe! -- there are manuals in the wild which can exceed the capabilities of the preprocessor (which has nothing to do with mdocmx(7) itself, but only circumvents missing multipass capabilities of troff(1)).
But note that nail.1 and tmac-mdoc.7.in are really, really complicated and i don't see any problems.
And if there is still a manual page which is even more complicated, then possibly it should be adjusted a bit, then.

Btw. the manual can now also be browsed online [1].
Of course that HTML version doesn't support references to external manual pages, as could be easily followed on the TTY via grotty(1) and in less(1).

  http://sdaoden.users.sourceforge.net/code-mdocmx.html

Thanks for your consideration.

Oops, groff-1_22_3.diff includes addition of a .hash troff(1) request!  This is of course no(t) (longer) needed!  Find attached the diff without .hash (otherwise identical).
Sorry!!

(file #33939)