Re: Plan 9 man added a new macro for man page references

[Alejandro Colomar (man-pages)]

Hi, Branden!

On 8/1/21 1:09 PM, G. Branden Robinson wrote:

I support this plan ;-)


Cool!  I'm glad to see some discussion about it...it would be _so nice_
to land this and OSC 8 hyperlinks for terminal emulators in grotty(1)
for the next groff release.  Those would be new features we could really
trumpet.

"30 years after Sir Tim Berners-Lee brought you HTML, groff is hot on
his heels!"

Well, maybe not.  You can see why I'm not in sales.


Thinking about it twice...

Given mdoc(7) already implemented that, and that the basic difference 
between mdoc(7) and man(7) is basically that man(7) is simple and 
doesn't have semantic macros (only style macros), and mdoc(7) was 
designed to superseed man(7) by having semantic macros instead of style 
macros (but with the side effect of being much more complex in the way), 
I think it would be wrong to "port" back (some of) those features back 
into man(7).


Either we should move to use mdoc(7), or we don't at all.  (And for the 
moment, I think I'll keep with the man(7) simpler macros.)


What are your thoughts?

Regards,

Alex

--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/

groff_man(7), man(7), and man-pages(7) (was: [PATCH v2] mount_setattr.2: ...)

[G. Branden Robinson]

[adding groff@ to CC]

Hi, Alex!

At 2021-08-01T13:50:09+0200, Alejandro Colomar (man-pages) wrote:
> [I (GBR) wrote]:
> > https://xkcd.com/927/
> 
> Agree.  That's why I doubt very much that we'll ever change to RST (or
> any other language).  But I'll have to try and make the current
> man-pages consistent enough so that people see it easy writing them...

We definitely share this goal.

> I think I tried groff_ms(7), or maybe it was groff_mm(7); I don't
> remember.  But I didn't like having to learn a new dialect, more so
> when there are macros that act differently with the same name.

Fair enough.  I have to admit that some things about ms(7) surprised me;
it was really aggressive with the use of diversions to collect input,
and its approach to font style alternation was a bit timid at first
which led to it being extended in a way which is tough to defend.

When Bell Labs took their second crack at a general-purpose macro
package, mm, they adopted man(7)'s names and semantics for font style
alternation.

Unfortunately, that approach doesn't scale well with the availability of
large numbers of fonts/styles.  (And design-wise, they got caught out in
short order with the radical novelty of the Linotron 202's bold italic
style.)

> Since I already know man(7) very well, it's simpler for me to use it
> everywhere.  But maybe if you send me that document you might convince
> me (but I doubt it).

Attached.  Since my last attempt to send a PDF to linux-man@ went into a
black hole, I'll send you the document source (which is smaller anyway).

Just format it with "groff -t -ms".  I've even gotten it usable on
terminals, though so far only on wide ones (at least 91 character cells;
getting it any narrower would mean refactoring the tables, and I've
deferred that until after I complete content revisions, if ever).

> I think most languages out there are perfect examples of
> .

This perspective, I don't share--I'm fond of C but also sometimes
maddened by it.  I think there is great value in exposure to other
languages, well enough to a get a "feel" for them if not to use them in
daily practice.  I think doing so can help one's creativity in
problem-solving.  To name two examples, I've seen much to admire in Ada
and Rust.  I'd like to grow a Haskell brain.

> BTW, I'm curious, and never knew this:  what's the difference between
> groff_man(7) and man(7)?  They are each a page about groff_man,
> written by different authors/projects, right?

Yes.  Michael and I were able to roughly sketch the history in a thread
in May[1].

What would you think about retiring the linux-man man(7)?  I've been
hesitant to suggest this because it does some work that I don't want
groff_man(7)[2] to do, because to do so is not its place--the
prescription of system-specific conventions and practices.  However, it
occurs to me that much of this information is already being maintained
more diligently in man-pages(7), and that which is truly more material
to system _organization_ is probably better suited to intro(7) or even
intro(1).

groff names its macro package man pages with a "groff_" prefix because
it was common, back in the 1990s, to install it on vendored, branded
Unix system that already supplied a troff system--often Documenter's
Workbench (DWB) troff, SoftQuad troff (sqtroff), or some descendant of
an AT&T troff (sometimes from before Kernighan's device-independent
rewrite of the system ca. 1980, sometimes later).

On systems where nothing else provides the macro packages, this makes
little sense.  groff_{man,mdoc,me,mm,ms}(7) might as well be available
simply as {man,mdoc,me,mm,ms}.  Slightly absurdly, we also have a page
named groff_mom(7) even though the mom macro package never existed in
_any_ other implementation.

I don't suggest a rename so much as an additional provision of an
additional set of pages with .so requests bringing up the "real" pages.
It's sort of like having symbolic links within the roff(7) language.

I would emphasize that because there is style guidance in
groff_man_style(7)[3], I think it would retain (only) that name even if
groff were to start providing man(7), because the former page documents
_groff's_ house style in areas where there is room for discretion).

> That's what I don't like

Yes, and it _still_ doesn't solve what we often call the "three-font
problem" (discussed, with workarounds, at length in groff_man_style(7)).

Bernd Warken, a groff contributor from several years, promoted a macro
called "FONT" that would take alternating arguments: a font identifier
followed by the argument to be set in it, repeat.

So, you might have

.FONT R [ B \-\-stylesheet= I file R ]

The above is as good a solution I've seen, but no one (apart from Bernd,
briefly) has expressed enthusiasm about extending man(7) with it.  I
think there are two reasons for that: (1) man needs more _semantic_
markup much more badly than it needs more style markup, and (2) there
are limited returns for d

Re: Why does refer(1) have no database field for "edition"?

[Tadziu Hoffmann]

> > Inaugurate a GNU extension?  

> Indeed, but the subject under discussion is making refer(1)
> conformant to various acknowledged styles, not in-house usage.

But isn't that the job of the macro package, not refer?

I guess the question is "How can refer make that job easier?",
which you answered by saying that mom defines a new database
field for the edition.  If we consider this usage the status
quo, should it be documented with an appropriate entry in the
list of field names in the refer manual page?

(The manual page does speak of the "conventional meaning" of
each field, implying that this is by common agreement rather
than by rule of an authority.)

Re: Plan 9 man added a new macro for man page references

[Ingo Schwarze]

Hello Alejandro,

Alejandro Colomar (man-pages) wrote on Tue, Aug 03, 2021 at 09:29:14AM +0200:

> Thinking about it twice...
> 
> Given mdoc(7) already implemented that, and that the basic difference 
> between mdoc(7) and man(7) is basically that man(7) is simple and 
> doesn't have semantic macros (only style macros), and mdoc(7) was 
> designed to superseed man(7) by having semantic macros instead of
> style macros

I consider that summary accurate.

> (but with the side effect of being much more complex in the way), 

I can't dispute the fact that the macro repertoire of mdoc(7)
is more complex than the macro repertoire of man(7).

But i never quite understood why people find using mdoc(7) more
complicated than using man(7), for several reasons.

 1. The mdoc(7) macro repertoire is quite small in absolute terms:
24 un-deprecated structure macros and
26 un-deprecated semantic macros.
The MACRO OVERVIEW for these can easily be seen in one
terminal window, all at the same time.
Yes, there are also about 11 physical markup macros
and about 3 useful text production macros,
but those hardly change the overall picture.
For comparison, DocBook is more than 5 times the size of mdoc(7),
and the texinfo(5) language is also sigificantly larger than mdoc(7).

 2. I find it easier to remember that a function name needs .Fn
than that it needs .B, or that a command line argument needs
.Ar than that it needs .I.  The amount of content type to macro
mappings you need to memorize (or look up) is exactly the same
for both languages, except that mdoc(7) has mnemonics and man(7)
has not.

 3. mdoc(7) has fewer syntactic quirks than man(7), not more.
A function argument needs .Fa, so it always gets .Fa, no matter
in which context.  In man(7) it sometimes needs .I, sometimes .IR,
sometimes .RI, and when it appears on the same line a bold *and*
roman content, you need a completely different syntax: escape
sequences, either \c or \f.  And that's just one example of
syntax complexity in man(7).

 4. For displays and lists, i claim that mdoc(7) .Bd and .Bl
syntax is not only more powerful and expressive, but actually
simpler and more uniform than man(7) .RS, .IP, .TP, .HP, and
.EX, without even needing as many macros.

 5. In the rare instances where man(7) does have limited semantic
markup, like .MT, .OP, .SY, .UR, it certainly isn't easier 
to use than the mdoc(7) equivalents, but it feels alien to the
rest of the man(7) language.

 6. When writing man(7) code, people regularly resort to using some
low-level roff features to fill gaps in the man(7) language.
That is almost never needed with mdoc(7), IMHO making the latter
easier to use than the former because you need less low-level
roff(7) skills.

 7. During the last decade, i deprecated several mdoc(7) macros
including .Bt, .Db, .En, .Fr, .Hf, .Li, .Lp, .Tn, .Ud, .Ux
and only added a single new one, .Tg.  So the language is
becoming simpler over time rather than growing.

 8. Existing BSD manual page corpusses use several macros for
historical reasons that would be trivial to avoid when adopting
the language for a new corpus, making the language even simpler,
for example .Os, .Bk, .Lb, .Ad, .Ms, .Bf, .Xo.
The OS text production macros (.At, .Bx, .Bsx, .Nx, .Fx, .Ox, .Dx)
would also not be strictly needed, reducing language size by
another seven macros.  So you would basically end up with
about 60 useful macros grand total.

> I think it would be wrong to "port" back (some of) those features back 
> into man(7).

That consideration does make sense to me.

When maintaining a programming or markup language, sparingly and
cautiously adding new syntax to fill isolated gaps in the feature set
often makes sense.

When a language is designed from the ground up with one programming
paradigm in mind - physical markup in the case of man(7) - redesigning
it for a completely different programming paradigm while in maintenance
mode seems like a questionable idea to me.

> Either we should move to use mdoc(7), or we don't at all.  (And for
> the moment, I think I'll keep with the man(7) simpler macros.)

*For the moment*, lots of constraints and tradeoffs usually have
to be considered, and i might understand if you come to the conclusion
that now is not the ideal time for you to adopt a language with a
more powerful paradigm.  Given that mdoc(7) has been available for
three decades, it is not a matter of life and death to adopt it
*right now*, it is a seasoned and time-proven language, it is
actively maintained, and will still be available for years to come.

> What are your thoughts?

In the long term, man(7) does not feel sustainable.  It was state of
the art in 1979, but missed the semantic markup revolution that
happened with HTML and mdoc about a decade after it was invented.

Note that you could rightfully say that mdoc(7) wa

Re: Why does refer(1) have no database field for "edition"?

[Peter Schaffter]

On Tue, Aug 03, 2021, Tadziu Hoffmann wrote:
> > Indeed, but the subject under discussion is making refer(1)
> > conformant to various acknowledged styles, not in-house usage.
> 
> But isn't that the job of the macro package, not refer?

Yes, it is.  My phrasing, above, was poor.
 
> I guess the question is "How can refer make that job easier?",
> which you answered by saying that mom defines a new database
> field for the edition.  If we consider this usage the status
> quo, should it be documented with an appropriate entry in the
> list of field names in the refer manual page?

Not unless (until?) it's implemented for all the canoncical macro
packages.  I proposed %e as a candidate for the edition field
because it's been around long enough in mom that it makes sense for
other macro packages to follow suit.  Plus it has the advantage of
being a meaningful mnenmonic.

> (The manual page does speak of the "conventional meaning" of
> each field, implying that this is by common agreement rather
> than by rule of an authority.)

That is indeed the case.  Field identifiers for refer(1) are
arbitrary.

Two things surprise me about what I'll call "the whole refer
picture."  One is that ms/mm/me do not implement fields for URLs and
other Web/Internet sources.  Mom implements five additional fields
for Internet sources as required by MLA:

  %s site name
  %c content (e.g. Web, Email, Blog...).
  %o organization, group, or sponsor or the site
  %a access date
  %u URL

Methinks, in 2021, that the other groff macro packages should catch
up with this newfangled Internet thingy.

The other is that nowhere is there any indication what style of
bibliographic formatting is provided by the ms/mm/me implementations
of refer(1), a matter of some importance for authors preparing
submissions and students writing papers.  Mom is upfront about
formatting in MLA style, which is useful to groffers seeking a macro
package that does MLA.  I believe the other packages should follow
suit and state, in their manpage or in refer(1), which style guide
is being followed for refer(1) bibliographies.

-- 
Peter Schaffter
https://www.schaffter.ca

Re: Plan 9 man added a new macro for man page references

[Alejandro Colomar (man-pages)]

Hi, Ingo!

On 8/3/21 4:30 PM, Ingo Schwarze wrote:

Hello Alejandro,

Alejandro Colomar (man-pages) wrote on Tue, Aug 03, 2021 at 09:29:14AM +0200:


Thinking about it twice...

Given mdoc(7) already implemented that, and that the basic difference
between mdoc(7) and man(7) is basically that man(7) is simple and
doesn't have semantic macros (only style macros), and mdoc(7) was
designed to superseed man(7) by having semantic macros instead of
style macros


I consider that summary accurate.


(but with the side effect of being much more complex in the way),


I can't dispute the fact that the macro repertoire of mdoc(7)
is more complex than the macro repertoire of man(7).

But i never quite understood why people find using mdoc(7) more
complicated than using man(7), for several reasons.


It is more complex (in the end with man(7) I end up using mainly .PP, 
.IP, .B, .I, and combinations of I, B and R, and then a few .RS/.RE, 
.EX/.EE, .SH and .SS), while mdoc(7) has quite more macros and less 
obvious ones (compared to these extremely simple ones).


But it's not necessarily extremely complicated; I mean, with some time 
I'd probably get it easy.  It's just that I learnt man(7) by necessity, 
and I haven't had the need to learn mdoc(7) yet, but I may some day.


But hey, I can transfer my man(7) knowledge easily to write other kinds 
of documents (done that; legal documents), and it scales well :)




  1. The mdoc(7) macro repertoire is quite small in absolute terms:
 24 un-deprecated structure macros and
 26 un-deprecated semantic macros.
 The MACRO OVERVIEW for these can easily be seen in one
 terminal window, all at the same time.
 Yes, there are also about 11 physical markup macros
 and about 3 useful text production macros,
 but those hardly change the overall picture.
 For comparison, DocBook is more than 5 times the size of mdoc(7),
 and the texinfo(5) language is also sigificantly larger than mdoc(7).

  2. I find it easier to remember that a function name needs .Fn
 than that it needs .B, or that a command line argument needs
 .Ar than that it needs .I.  The amount of content type to macro
 mappings you need to memorize (or look up) is exactly the same
 for both languages, except that mdoc(7) has mnemonics and man(7)
 has not.


That's true... partly.  I'd say that with a consistent man-pages corpus, 
it would be easier to know what you have to use, just by looking at 
other pages, but we don't have that at the moment (and it's one of my 
long term goals here).




  3. mdoc(7) has fewer syntactic quirks than man(7), not more.
 A function argument needs .Fa, so it always gets .Fa, no matter
 in which context.  In man(7) it sometimes needs .I, sometimes .IR,
 sometimes .RI, and when it appears on the same line a bold *and*
 roman content, you need a completely different syntax: escape
 sequences, either \c or \f.  And that's just one example of
 syntax complexity in man(7).


Yup.  From what I've seen, Linux man-pages have been ignoring the 
recommended style when there were three fonts mixed, and instead have 
used (somewhat incorrectly) 2 fonts, in exchange for simplicity.


However, now I'm trying to fix that and it doesn't seem so much complex 
(yes, it involves \c).




  4. For displays and lists, i claim that mdoc(7) .Bd and .Bl
 syntax is not only more powerful and expressive, but actually
 simpler and more uniform than man(7) .RS, .IP, .TP, .HP, and
 .EX, without even needing as many macros.

  5. In the rare instances where man(7) does have limited semantic
 markup, like .MT, .OP, .SY, .UR, it certainly isn't easier
 to use than the mdoc(7) equivalents, but it feels alien to the
 rest of the man(7) language.

  6. When writing man(7) code, people regularly resort to using some
 low-level roff features to fill gaps in the man(7) language.
 That is almost never needed with mdoc(7), IMHO making the latter
 easier to use than the former because you need less low-level
 roff(7) skills.

  7. During the last decade, i deprecated several mdoc(7) macros
 including .Bt, .Db, .En, .Fr, .Hf, .Li, .Lp, .Tn, .Ud, .Ux
 and only added a single new one, .Tg.  So the language is
 becoming simpler over time rather than growing.
 >   8. Existing BSD manual page corpusses use several macros for
 historical reasons that would be trivial to avoid when adopting
 the language for a new corpus, making the language even simpler,
 for example .Os, .Bk, .Lb, .Ad, .Ms, .Bf, .Xo.
 The OS text production macros (.At, .Bx, .Bsx, .Nx, .Fx, .Ox, .Dx)
 would also not be strictly needed, reducing language size by
 another seven macros.  So you would basically end up with
 about 60 useful macros grand total.



Hmmm, much more than what's in my head right now from man(7), but not an 
exaggerate number.




I think it would be wrong to "port" back (some of) those fea

Re: Plan 9 man added a new macro for man page references

[Dave Kemper]

On 8/3/21, Ingo Schwarze  wrote:
> When maintaining a programming or markup language, sparingly and
> cautiously adding new syntax to fill isolated gaps in the feature set
> often makes sense.
>
> When a language is designed from the ground up with one programming
> paradigm in mind - physical markup in the case of man(7) - redesigning
> it for a completely different programming paradigm while in maintenance
> mode seems like a questionable idea to me.

Those seem sound as general principles, but I think what's under
discussion here falls more solidly under the former paragraph above
than the latter.  The proposal is the addition of a single macro,
hardly a paradigm-shifting move.  And part of man's paradigm, from the
start, was viewing documentation in a terminal.  A user viewing one
page might learn that the information she needs is on a different page
-- a situation also present from day one.  The proposal before us is
merely simplifying the process of getting to that new page.  This is
advantageous to the user, but hardly a paradigm shift of the markup
language.

Though HTML was not one of man's original output choices, man pages
have also been rendered that way for decades now, and this is not
going away any time soon.  Links are an integral part of HTML, and any
information within the man page source to assist or improve that sure
seems like a step forward.

I can understand the reluctance to undertake the huge task of moving
an entire documentation set from one markup language to another, even
if the new language already includes this functionality.  But the
fairly simple extension to the man language proposed in this thread:

 - breaks no existing pages; man pages that fail to use it simply lack
these cross links, as they have since the '70s
 - adds useful functionality to those pages that do choose to use it
 - brings groff's man implementation into parity with another roff's
man implementation that already implements it

So there seems little downside to making the feature available in
groff even if some individual projects decline to use it.

Re: Plan 9 man added a new macro for man page references

[Ingo Schwarze]

Hi Alejandro,

Alejandro Colomar (man-pages) wrote on Tue, Aug 03, 2021 at 10:23:09PM +0200:
> On 8/3/21 4:30 PM, Ingo Schwarze wrote:
>> Alejandro Colomar (man-pages) wrote on Tue, Aug 03, 2021 at 09:29:14AM +0200:

[...]
>>   2. I find it easier to remember that a function name needs .Fn
>>  than that it needs .B, or that a command line argument needs
>>  .Ar than that it needs .I.  The amount of content type to macro
>>  mappings you need to memorize (or look up) is exactly the same
>>  for both languages, except that mdoc(7) has mnemonics and man(7)
>>  has not.

> That's true... partly.  I'd say that with a consistent man-pages corpus, 
> it would be easier to know what you have to use, just by looking at 
> other pages, but we don't have that at the moment (and it's one of my 
> long term goals here).

I agree with all of that.  Jason McIntyre and myself also routinely
counsel prospective authors to look at good manual pages for
inspiration for their own manual pages.  By the way, the same holds
for program code, too: reading good code in any programming language
is one good way to improve your own coding style and skills in that
language.

Note that such a complete corpus *is* available, even though not
as part of the Linux man pages project.  The main authors and
maintainers have been Cynthia Livingston (BSD CSRG / USENIX), Aaron
Campbell (OpenBSD) and Jason McIntyre (OpenBSD).  It covers almost
all of POSIX plus many additional functions and programs.  The
FreeBSD and NetBSD projects have manual pages evolved from the same
corpus, though maybe not quite as polished as in OpenBSD on because
they don't quite have the equivalent of Jason.

[...]
> There are a few considerations:
> 
> - Neither Michael nor I do have a lot of time these times (the next 
> release of the man-pages (5.13), which should be released soon, will
> be quite small because of that).

That's no doubt a valid consideration.

> - I have other more prioritary fixes for the pages:
>- Fixing the includes in the examples
>- Documenting types in system_data_types(7)
>- Add a LIBRARY section (as in FreeBSD pages) to simplify the current 
> text that provides that information in a mix of sections.
>- Some other consistency fixes.
> 
> - I would like to have the pages consistently use man(7) before ever 
> considering a language change.  The thing, and this is only a prediction 
> of mine, is that when we have the pages more consistent than now, it 
> should be even easier to use man(7), and incoming patches should be more 
> correct on average, so there will be less reason to move to another 
> language/dialect.

You are certainly right that consistency generally helps providing
good examples to patch submitters and consequently improves quality
and reduces everyone's workload.

> - There are some benefits, as it seems, but enough to make such a big 
> change?  Not sure.

The two main benefits are:

 1. Better markup.  Compare:

https://man.openbsd.org/ksh.1

which is an mdoc(7) page to man(7) pages like

https://man.openbsd.org/as.1
https://man.openbsd.org/cc.1
https://man.openbsd.org/gdb.1
https://man.openbsd.org/tic.1

In particular, watch out for everything underlined - solid
underlining indicates hyperlinks, dotted underlining indicates
deep linking targets.  Also hover your mouse over marked-up
words to see the syntactic function of the word displayed in a
tool tip.  In all these respects, mdoc(7) works significantly
better than man(7).  The few such features available in the
man(7) pages are mostly based on crude heuristic guesswork
and quite incomplete.

Note that the HTML rendering engine of

https://manpages.debian.org/

is fully equipped to profit from all these features.
So far, Michael Stapelberg merely chose to use his own CSS code
instead of the one provided upstream, and that CSS ignores many
of the possibilities.

 2. Powerful semantic searching, for example:

# Pages containing cross references to "chmod"
https://man.openbsd.org/?query=Xr%3Dchmod&apropos=1

# Pages referencing C preprocessor macros containing INADDR
https://man.openbsd.org/?query=Dv%3DINADDR&apropos=1

# Programs having internal "bind" commands
https://man.openbsd.org/?query=Ic%3Dbind&apropos=1

# Pages mentioning files containing "fstab" in their name
https://man.openbsd.org/?query=Pa%3Dfstab&apropos=1

# Functions throming the ESRCH errno
https://man.openbsd.org/?query=Er%3DESRCH&apropos=1

# Programs using the COLUMNS environment variable
https://man.openbsd.org/?query=Ev%3DCOLUMNS&apropos=1

# Functions defined in 
https://man.openbsd.org/?query=In%3Dctype.h&apropos=1

# Software authored by Markus Friedl
https://man.openbsd.org/?query=An%3DFriedl&apropos=1

# Features available sinc AT&T Version 1 UNIX
https://man.openbsd.org/?query=At%3Dv1&apropos=1

Of cours

Re: Plan 9 man added a new macro for man page references

[G. Branden Robinson]

Hi Alex & Ingo,

I owe Doug McIlroy an apology for, some months ago on this list,
significantly understating his diligence as editor of Volume 1 of the
Version 7 Unix manual (1979).  A meticulously numerical accounting of
just one aspect of that effort follows in this (lengthy) email.

At 2021-08-01T14:06:38+0200, Alejandro Colomar (man-pages) wrote:
> > For more on what can go wrong you when you screw up concurrency,
> > see
> > .MR membarrier "2 Errors" .
> 
> Interesting.  You could make it search for SH and SS coincidences.

They don't have to be coincidences; it's possible to extend SH and SS
themselves to plant "anchor targets" which can be used by MR.  Such an
extension involves *roff "device escapes" (probably using groff's
devtags.tmac) and would not be visible to, or require anything of, the
man page writer at all.

> I think a 3rd (or maybe a 4th if the 3rd corresponds to the
> punctuation) argument would be better, as it doesn't have very much
> relation to the 2nd one.  It will be simpler to understand in separate
> arguments.

That's true; I have a competing bias to keep more closely related things
topologically closer.

> > > I support this plan ;-)

I've noted you've cooled off on this.  Ingo's a more seasoned campaigner
than I am.  :-O

> > You can see why I'm not in sales.
> I have alx.manpages@ for normal usage, and then alx.mailinglists@ for
> subscribing to mailing lists.  That way I avoid noise in the other one
> (I'm subscribed to libc-alpha@, linux-man@, linux-api@, which are
> very-high traffic).  And groff@ mails may get lost between many of
> those linux-api@ and libc-alpha@ mails.  That's also why I prefer that
> people CC me in patches instead of sending them only to linux-man@
> (there they may get lost) (Michael too BTW, for similar reasons).

Understood, and honored above.

At 2021-08-01T15:49:25+0200, Ingo Schwarze wrote:
> Hi Branden,
> 
> note that mdoc(7) has most of what you are talking about - not just
> as a freshly invented concept yet to be tested, but actively used
> and proven adequate in practice.  In particular the .Xr macro has
> seen consititent use in all mdoc(7) manual pages for more than 30
> years, and it has been in use for hyperlinking on the web for about
> ten years, or even much longer if you count the original FreeBSD
> man.cgi implementation.  It has exactly the syntax you propose for
> .MR:
> 
>   .Xr page_name section_number [punctuation_suffix_args]

I'm aware.  And parallelism between the macro interfaces on this point
seems like a feature rather than a bug.

I will however note that groff mdoc does not regard a single-argument
call to Xr as an error condition as mandoc does.  This mode of calling
it has a use case that we exercise in the groff_mdoc(7) page; I asked
you about it in December[1] and haven't heard back.

> I first discussed that idea during EuroBSDCon 2015 in Stockholm:
> 
>   https://www.openbsd.org/papers/eurobsdcon2015-mandoc.pdf
>   see pages 15 to 18
> 
> It turns out the concept of remote deep linking in manual pages is
> rarely needed, for several reasosn.
> 
> Well-designed programs tend to be simple, doing one thing well.

Even granting this arguendo--I'm not sure it holds for programs that
aren't _designed_ to participate in the Unix pipeline/filter
model--there are plenty of counterexamples in the field with a long and
successful history, like ffmpeg and ImageMagick/GraphicsMagick.

I know you have an even stronger prescriptivist bent than I do, and so
your response might be to leave such ill-conceived programs
undocumented, thus hastening their deaths in the hopes that
philosophically pure replacements will come along and which will
incidentally fit neatly into the mdoc(7) schema without requiring deep
links.

That might be the OpenBSD way, but it's not how many GNU/Linux
distributions operate; they're eclectic, and for better or worse
assimilate software projects that adhere weakly or not at all to that
principle.  Some of the people who use them are going to want to see
them documented.  A few of those, perceiving a lack of documentation,
are going to want to supply it.

> Consequently, well-written manual pages for well-designed programs
> tend to be short.  When linking to a short document, deep linking
> matters little.  Besides, deep linking is not necessarily beneficial.
> The reader being refered to that other page needs to grasp some
> context regarding what that other page is about, and that is easiest
> to get from the page title, the Synopsis section, and the first
> sentence of the Description section - i.e. from the beginning of the
> page.  Being plunged right into the middle of a document is not always
> helpful, *especially* when the document is large or complex.

Some readers, you can trust to recognize when they're missing context
and to "zoom out" with respect to the scope that the reference takes
them.

[...]
> I'm not saying deep linking is completely irrelevant or i would not
> habe be

Re: pdfmark: need a method to sanitize text in document outlines

[G. Branden Robinson]

Hi, Keith!

At 2021-08-02T16:30:47+0100, Keith Marshall wrote:
> I don't recall noticing this before, (probably an oversight on my
> part), but if I regenerate pdfmark.pdf today, from pdfmark.ms, I see
> several document outline entries similar to:
> 
>   The F[C]pdfmarkF[] Operator
> 
> In this, the (unwanted) F[C] and F[] appear to be artefacts from the
> likes of:
> 
>   .NH 2
>   .XN The \F[C]pdfmark\F[] Operator
> 
> where XN is a locally defined macro which emits its entire argument
> list as the text for the numbered heading, while also constructing a
> table of contents entry, and a document outline entry, from the same
> arguments.
> 
> Clearly, the formatting escape sequences need to be filtered out of (a
> copy of) the argument list, before passing it to the pdfbookmark
> macro.
[...]

I don't have a solution for you but I think I do have a similar problem.

I wanted to implement the missing SG ms(7) macro (available in V7 Unix
troff but not groff), but got stuck because authors are stored in a
diversion instead of being passed as macro arguments.  That means they
can do all kinds of complicated things.  So if you try to pop them again
for .SG purposes they'll come out _exactly_ as the diversion had
prepared them, complete with unhelpful,
possibly-redundant-in-their-original-context centering requests and so
forth.

Probably there's nothing that can be done about this in ms(7) for
historical reasons; I suppose the advice would be "don't do that with
your authors, then!" if you want to use the SG macro.  (Or just don't
use SG, which seems to suit most groff ms users, given the paucity of
documented complaints about its absence.)

Maybe what we need is something stronger than 'asciify' (a regrettable
name in the age of Unicode)--maybe 'stringify': something that will
discard everything from a stored string or diversion that isn't an
ordinary or special character.  But we'll still, I think, face a problem
our Texinfo manual warns about.

@code{asciify} cannot return all items in a diversion back to
their source equivalent; nodes such as those produced by the
@code{\N} escape will remain nodes, so the result cannot be
guaranteed to be a pure string.  @xref{Copy Mode}.

(Hmm--that semicolon should be a colon.)

I don't feel I understand these issues completely, so I might be off
base.

Regards,
Branden


signature.asc
Description: PGP signature