[bug #45034] mdoc(7): add support for the mdocmx(7) reference extension

[anonymous]

Follow-up Comment #11, bug #45034 (project groff):

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+ Cv'-.1v'h'-1p's-2+h'-1p'+s0v'.1v'h'-1p'

.Sh DESCRIPTION
.Ss Dq Blabla
.Ss "s-1OPTIONSs0"
.Ss "Options Controlling *(C+ Dialect"
.Ss "Using fBgcovfP with s-1GCCs0 Optimization"
.Ss "Extension based on fI.hfP and fI.cfP files"
.Ss "Fixed parsing of $$<digit>, &$<digit>, etc."
.Ss "-s, --shuffle"
.Ss "new ( [s-1OPTIONSs0] )
.Ss "report Bundle|Distribution|Module"
.Ss "upgrade [Module|/Regex/]..."
.Ss "_search_module_tree( type => s-1TYPEs0, allow => address@hidden, [data =>
address@hidden ] )"
.
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]

address@hidden@[4]
   @address@hidden
   address@hidden@[12]
   Options Controlling C++ address@hidden@[13]
   Using gcov with GCC address@hidden@[14]
   Extension based on .h and .c address@hidden@[15]
   Fixed parsing of $$<digit>, &$<digit>, address@hidden@[16]
   -s, address@hidden@[17]
   new ( [OPTIONS] )@address@hidden
   report Bundle|Distribution|address@hidden@[19]
   upgrade [Module|/Regex/address@hidden@[20]
   _search_module_tree( type => TYPE, allow => @regexex, [data =>
     @previous_results ] )@address@hidden
     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.)

    _______________________________________________________

Reply to this item at:

  <http://savannah.gnu.org/bugs/?45034>

_______________________________________________
  Message sent via/by Savannah
  http://savannah.gnu.org/