Re: Milestone reached: hyperlinked mdoc(7) documents in PDF

[Deri]

On Friday, 22 March 2024 16:59:14 GMT Alejandro Colomar wrote:
> ow, how am I supposed to
> get that patch without anyone tampering it during its trip to my
> computer?  :(

derij@ws:~$ md5sum  /var/www/chinese.patch.gz 
109e2681b7402ca55118226aa575b6d3  /var/www/chinese.patch.gz

Re: Milestone reached: hyperlinked mdoc(7) documents in PDF

[Alejandro Colomar]

On Fri, Mar 22, 2024 at 05:56:58PM +, Deri wrote:
> On Friday, 22 March 2024 16:59:14 GMT Alejandro Colomar wrote:
> > ow, how am I supposed to
> > get that patch without anyone tampering it during its trip to my
> > computer?  :(
> 
> derij@ws:~$ md5sum  /var/www/chinese.patch.gz 
> 109e2681b7402ca55118226aa575b6d3  /var/www/chinese.patch.gz

Hi Deri!

That matches what I downloaded back then; thanks!  :)

BTW, is that font available in any Debian package?  Maybe we can get it
from there, and add a dependency on such a package, to avoid adding the
font to the repository?  There's a 'unifont' Debian package, which I
guess is related to this, right?

Cheers,
Alex

-- 

Looking for a remote C programming job at the moment.


signature.asc
Description: PGP signature

Re: Milestone reached: hyperlinked mdoc(7) documents in PDF

[Alejandro Colomar]

Hi Branden!

On Fri, Mar 22, 2024 at 11:30:11AM -0500, G. Branden Robinson wrote:
> Hi Alex,
> 
> At 2024-03-17T23:44:07+0100, Alejandro Colomar wrote:
> > On Sun, Mar 17, 2024 at 05:23:20PM -0500, G. Branden Robinson wrote:
> > > Following up my earlier announcement regarding man(7),[1], I'm
> > > pleased to report that we have a functioning PDF hyperlink story for
> > > the mdoc package.
> [...]
> > > P.S. Alex, you might want to consider simplifying your cover page
> > >  similarly once you bring your copy of groff up to date.
> > 
> > How much would you consider having a release sooner than expected, and
> > then have what originally would have been 1.24.0 be 1.25.0?  :)
> 
> Not very much.  As I noted previously, I'm still not the official GNU
> maintainer of groff.  (This is partly procrastination and partly
> consideration for Bertrand's very tight time budget for GNU work.)

Please, please :)

> 
> > I would prefer using a packaged version of groff, for two reasons:
> > 
> > -  I got impedance mismatches, when I see stuff like the 5n base-
> >paragraph indent, but contributors are still seeing 7n.
> 
> Fair.  You _can_, of course, configure groff Git to replicate the output
> line arrangement of groff 1.23.0 and earlier, with `-rBP=7n -rLL=78n`.

I'm not a fan of configuring stuff either, because then I forget that I
did.  And I do like 5n.  I would like others to also have it, rather
than not having it myself.  :)

> > -  In my server, I have a script that builds the man-pages book for
> >every push to the main branch (true for both the Linux man-pages
> >and shadow), and another that runs the lints and checks for the
> >Linux man-pages.  Having built-from-source software in my computer
> >is less of a problem, but in a server, it's less comfortable.  (I
> >already have Deri's branch in there, and I'm not in love with
> >that.)
> 
> You're a good person to ask; is there anything from Deri's branch that
> Linux man-pages still needs?

I started using it because of the cyrillic shadow manual pages.
groff-1.23.0 has issues with them.

If you have some time for it, I'll bombard you with some questions and
requests for the Linux man-pages book-generating scripts.  :)

>  I know it has some stuff you probably
> _don't_ need, like the slanted symbol font and a new approach to
> associating glyphs in groff font description files with Unicode code
> points.
> 
> > But yeah, I'm willing to simplify as much as possible!  ;)
> 
> I won't pressure you.  If I recall correctly I still owe you another
> preliminary to the Most Disruptive Automated Change Ever Unleashed on a
> Man Page Corpus ("MR.sed"), that being something to do with man page
> cross references inside tbl(1) tables.  I'll have to review the email
> thread from January.

I don't remember what was remaining, but I think almost everything was
done.  We are missing just the final pieces, IIRC.  Still, if you manage
to simplify the sed(1) script by applying some pre-patches, it would be
easier to review.

Which reminds me of the discussion about PGP signatures on patches we
had some moons ago (something that Deri reminded me unintentionally
recently too): Deri posted a gigantic patch with a new font for
supporting the zh_CN manual pages from shadow in the PDF book.  But he
didn't sign anything, and he just posted a link to his (HTTP) web server
where his patch is hosted for me to wget(1).  Now, how am I supposed to
get that patch without anyone tampering it during its trip to my
computer?  :(

> By the time I get to it, the argument that groff 1.23 is "too new" will
> be pretty feeble...

Actually, I didn't pressure you, because that might give some time to
Ingo to add support for MR in mandoc(1).  But I didn't hear anything
from him in a long time.  But yeah, I'm ready to patch the Linux
man-pages whenever you send your next revision.

Have a lovely Spring!
Alex

> Regards,
> Branden


-- 

Looking for a remote C programming job at the moment.


signature.asc
Description: PGP signature

Re: Milestone reached: hyperlinked mdoc(7) documents in PDF

[G. Branden Robinson]

Hi Alex,

At 2024-03-17T23:44:07+0100, Alejandro Colomar wrote:
> On Sun, Mar 17, 2024 at 05:23:20PM -0500, G. Branden Robinson wrote:
> > Following up my earlier announcement regarding man(7),[1], I'm
> > pleased to report that we have a functioning PDF hyperlink story for
> > the mdoc package.
[...]
> > P.S. Alex, you might want to consider simplifying your cover page
> >  similarly once you bring your copy of groff up to date.
> 
> How much would you consider having a release sooner than expected, and
> then have what originally would have been 1.24.0 be 1.25.0?  :)

Not very much.  As I noted previously, I'm still not the official GNU
maintainer of groff.  (This is partly procrastination and partly
consideration for Bertrand's very tight time budget for GNU work.)

> I would prefer using a packaged version of groff, for two reasons:
> 
> -  I got impedance mismatches, when I see stuff like the 5n base-
>paragraph indent, but contributors are still seeing 7n.

Fair.  You _can_, of course, configure groff Git to replicate the output
line arrangement of groff 1.23.0 and earlier, with `-rBP=7n -rLL=78n`.

> -  In my server, I have a script that builds the man-pages book for
>every push to the main branch (true for both the Linux man-pages
>and shadow), and another that runs the lints and checks for the
>Linux man-pages.  Having built-from-source software in my computer
>is less of a problem, but in a server, it's less comfortable.  (I
>already have Deri's branch in there, and I'm not in love with
>that.)

You're a good person to ask; is there anything from Deri's branch that
Linux man-pages still needs?  I know it has some stuff you probably
_don't_ need, like the slanted symbol font and a new approach to
associating glyphs in groff font description files with Unicode code
points.

> But yeah, I'm willing to simplify as much as possible!  ;)

I won't pressure you.  If I recall correctly I still owe you another
preliminary to the Most Disruptive Automated Change Ever Unleashed on a
Man Page Corpus ("MR.sed"), that being something to do with man page
cross references inside tbl(1) tables.  I'll have to review the email
thread from January.

By the time I get to it, the argument that groff 1.23 is "too new" will
be pretty feeble...

Regards,
Branden


signature.asc
Description: PGP signature

Re: mandoc(1)'s man pages, groffed, and Project KIC (was: Milestone reached: hyperlinked mdoc(7) documents in PDF)

[Lennart Jablonka]

Quoth Dave Kemper:

On Tue, Mar 19, 2024 at 1:28 PM Lennart Jablonka  wrote:

replace Courier by a non-fixed-width type face, because we really don’t
need to emulate the nonsense typewriters do in print.


True if it were emulating only typewriters, but fixed-width fonts are
still very common in terminal emulators.  So a font that emulates that
aspect of characters to be typed at the terminal is a helpful cue to
readers.  (Not a defense of Courier itself, but of monospace fonts in
certain contexts.)


Right.  We can emulate the nonsense typewriter /emulators/ do.  
I do think that we shouldn’t do that, either.

Re: mandoc(1)'s man pages, groffed, and Project KIC (was: Milestone reached: hyperlinked mdoc(7) documents in PDF)

[Dave Kemper]

On Tue, Mar 19, 2024 at 1:28 PM Lennart Jablonka  wrote:
> replace Courier by a non-fixed-width type face, because we really don’t
> need to emulate the nonsense typewriters do in print.

True if it were emulating only typewriters, but fixed-width fonts are
still very common in terminal emulators.  So a font that emulates that
aspect of characters to be typed at the terminal is a helpful cue to
readers.  (Not a defense of Courier itself, but of monospace fonts in
certain contexts.)

Re: mandoc(1)'s man pages, groffed, and Project KIC (was: Milestone reached: hyperlinked mdoc(7) documents in PDF)

[Lennart Jablonka]

Quoth G. Branden Robinson:

And the page numbers reset at the start of each section.  Which they
shouldn’t do—the book is one unit; it should get its own page numbers.
And in other books, you don’t usually see page numbers per chapter.


This was a bug in me, not in groff.  I forgot to specify `-rC1` when
generating the PDF.  Include it, and one gets 160 pages (using U.S.
letter paper) numbered consecutively.


How come that is not the default?


(“Section” being an older term for “man pages,” if memory serves
right.)


Not as far as I know.  I use the term "document" when it's important to
distinguish between a coherent chunk of man(7) or mdoc(7) with one `TH`
or `Dd` call, respectively, and the face of a (perhaps digitally)
printed "leaf".


The v7 Introduction indeed calls 1, 2, … 8 “sections” and sh(1) 
and the like “entries.”  But v7 man(1) says:



NAME
man - print sections of this manual

SYNOPSIS
man [ option ... ] [ chapter ] title ...

DESCRIPTION
Man locates and prints the section of this manual named
title in the specified chapter.  (In this context, the word
`page' is often used as a synonym for `section'.)  The title
is entered in lower case.  The chapter number does not need
a letter suffix.  If no chapter is specified, the whole
manual is searched for title and all occurrences of it are
printed.

[…]


Also, from volume 1 page iii:

The page numbers of each entry start at 1; it is infeasible to 
number consecutively the pages of a document like this that is 
republished in many variant forms.


Huh.  I don’t agree.


Though Courier is as ugly as ever.


I'm glad you brought this up.  I vigorously agree.  I think inline (as
opposed to "displayed" changes of font family are generally a terrible
idea.  And yes, I know some luminaries do it in their books--Brian
Kernighan for example.  But he also takes authorial care with the
clarity and quality of the result.  (I've been enjoying the recent 2nd
edition of _The AWK Programming Language_ lately.)


Also a good point, though not what I meant.  I think Courier 
itself is an ugly type face.



mdoc(7) pages typeset by groff have numerous deficiencies, motivated I
think by some misguided notion that if something was "literal", or maybe
not "literal" but something that a user was going to _make_ literal when
they typed it in (through parametric replacement), it should be
formatted in Courier.

I simply cannot subscribe to that principle.  I reject it violently.


Sure, but it would be a win already to replace Courier by 
a different fixed-width type face.  But that’s site-local 
configuration, I guess.


It would be better still to replace Courier by a non-fixed-width 
type face, because we really don’t need to emulate the nonsense 
typewriters do in print.



I've been tempted more than once to just nuke these "C"s.  I generally
haven't done it, and any such meddling is sure to bring strident
complaint from some quarters.  наб ripped me a new excretory orifice
when I "demoted" the output of `Nm` from bold to normal weight in the
"Name" section of the page.[1]


Dew it!


2.  Again, I have _no_ objection to Courier in _displays_.  And mdoc(7)
   has those.  I'd like to see how far we can get with a strategy of
   assigning these doc-XX-font strings only _style_ changes, and leave
   it to block-structured macros like `Bd -literal`, `Ed` to change the
   font family.  There's a problem to be solved with `Bl`/`El`.  I'll
   need to learn my way around these heavily ornamented macros to grasp
   the shape of it.  Fortunately, examples of usage are not scarce.


I do object to Courier in displays.  Courier is ugly.  Ugly, ugly, 
ugly.  Even under the fixed-width type faces, there are 
nice-looking ones.  Courier is not one of those.  Courier is ugly.

mandoc(1)'s man pages, groffed, and Project KIC (was: Milestone reached: hyperlinked mdoc(7) documents in PDF)

[G. Branden Robinson]

[dropping Alex from To: header]

Hi Lennart,

At 2024-03-18T21:13:32+, Lennart Jablonka wrote:
> I wouldn’t at all be surprised by what I’d call errors in the mandoc
> man pages, as I guess they aren’t tested a whole lot with more general
> troffs and the project calls mdoc not a macro package or the like, but
> its own language.

Ordinarily I'd characterize that sort of claim as overstated, but mdoc
does bend the *roff language hard.

> > Do you find the attached "groffed" mandoc collection an improvement?

[rearranged]

> And the page numbers reset at the start of each section.  Which they
> shouldn’t do—the book is one unit; it should get its own page numbers.
> And in other books, you don’t usually see page numbers per chapter.

This was a bug in me, not in groff.  I forgot to specify `-rC1` when
generating the PDF.  Include it, and one gets 160 pages (using U.S.
letter paper) numbered consecutively.

> (“Section” being an older term for “man pages,” if memory serves
> right.)

Not as far as I know.  I use the term "document" when it's important to
distinguish between a coherent chunk of man(7) or mdoc(7) with one `TH`
or `Dd` call, respectively, and the face of a (perhaps digitally)
printed "leaf".

> Though Courier is as ugly as ever.

I'm glad you brought this up.  I vigorously agree.  I think inline (as
opposed to "displayed" changes of font family are generally a terrible
idea.  And yes, I know some luminaries do it in their books--Brian
Kernighan for example.  But he also takes authorial care with the
clarity and quality of the result.  (I've been enjoying the recent 2nd
edition of _The AWK Programming Language_ lately.)

mdoc(7) pages typeset by groff have numerous deficiencies, motivated I
think by some misguided notion that if something was "literal", or maybe
not "literal" but something that a user was going to _make_ literal when
they typed it in (through parametric replacement), it should be
formatted in Courier.

I simply cannot subscribe to that principle.  I reject it violently.

One of the problems it causes is that as a stream of text is performing
the Times and Courier switcheroo by the word, it becomes difficult to
tell when a space between words is present.  Courier is monospaced and
its space width is really fat.  Times is not and its space width is
pretty narrow.  In command synopses, it is often hard to tell whether
there is a space before or after a square bracket, for example, because
the brackets, not being "literal", are therefore by this arc-welded
principle of coupling, in Times.  You can observe these problems
starting at the top of page 1 of the mandoc-groffed PDF.  They are
immediately conspicuous.  Look how close together a _closing_ square
bracket is to a subsequent _opening_ one.  Is a space implied there?
You think so?  Look at that fat space after "-M" and before "path".  Are
you still sure?  Probably, if you already understand Unix command
conventions and don't really need to be reading this man page in the
first place.  This is the Neuschwanstein Castle of the clubhouse
experts; "the experienced user will know what is [right]."

No, this is _terrible_ ergonomics.  And, I submit, bad typography.

All people have to do to test my claims is to look at the collected
mandoc man page PDFs I've shared.

> Another place is, on the same page, “( expr  )” as the first tag of
> the tagged list at the end.

That's the exact problem I'm talking about above.  Only one space
follows "expr" (select it in your PDF tool and see) but it's in Courier,
not Times, as the parentheses are.

But yes!  It absolutely does LOOK like two spaces.  People don't read
documentation by selecting it by the character cell in a PDF viewer.
They read it with their eyes and this slavish devotion to Courier for
"literals", even when as here, the argument _isn't even literal_, is
erecting a barrier to comprehension and to simple pleasant reading.

Bad, bad, bad.  I don't know who's behind these choices but I fear I've
made an enemy for life.  (Get in line, eh?)

> And on page 1 (See?  But I do indeed mean the first page of
> apropos(1).), in the second paragraph of the DESCRIPTION, you can see
> too much space after “Nm.”  That happens in a few places.  

Here's the, uh, pellucid macrology behind the exhibit in question.

.Pq the Li \ No and Li \ No macro keys .

Because `Nm` is `Li`teral here (and protected from interpretation by
mdoc(7)'s internal macro system by the dummy character), it gets set in
Courier.  And because `Li` happily eats arguments until hitting a
special one--an mdoc(7) macro name, an item of punctuation, and possibly
some other exceptions a real mdoc maven would add to this list,
haughtily correcting my scandalous ignorance--it can't know to switch
the font face back yet.  The space _has_ to be in Courier.

The thing is, nearly all of this problem is an unnecessary own-goal,
created not with sophisticated macro programming firepower--which every
implementation of mdoc(7) 

Re: Milestone reached: hyperlinked mdoc(7) documents in PDF

[Lennart Jablonka]

Quoth G. Branden Robinson:

There may be some malformedness here complicating matters.


My example of .No Ar is not malformed: The No there is useless, 
yes, but that shouldn’t break anything.  The warning is a warning 
of the uselessness, not a warning of unspecifiedness.  I simply 
wanted to point toward Ar being called as argument to a different 
macro, disregarding what the exact macro is that is invoked 
directly and calls Ar.


What makewhatis(8) does (.Fl t Ar) might have been a better 
example, but wouldn’t have illustrated that the error is not in 
the .Fl t or in the .Ar invocation but in the /called/ Ar.  
I think.



It's possible this is an error in a mandoc man page.  Unthinkable?  ;-)


I wouldn’t at all be surprised by what I’d call errors in the 
mandoc man pages, as I guess they aren’t tested a whole lot with 
more general troffs and the project calls mdoc not a macro package 
or the like, but its own language.



At 2024-03-18T12:56:45-0500, G. Branden Robinson wrote:

...and in fact when I change line 9:

-.No Ar
+.No \

...the applicable warnings from groff mdoc _and_ mandoc go away, and
the text formats as you would expect.


The foregoing can be mostly disregarded.  I forgot that mdoc(7)'s `Ar`
macro supplies its own "default arguments" in the absence of explicit
ones, so it's okay to call it with none.


And that Ar is a macro that I want to call here.  `.No \` 
renders as one might expect, but not as one would expect if typing 
`.No Ar`.



Do you find the attached "groffed" mandoc collection an improvement?


Yes.  Though Courier is as ugly as ever.  And the page numbers 
reset at the start of each section.  (“Section” being an older 
term for “man pages,” if memory serves right.)  Which they 
shouldn’t do—the book is one unit; it should get its own page 
numbers.  And in other books, you don’t usually see page numbers 
per chapter.


And on page 1 (See?  But I do indeed mean the first page of 
apropos(1).), in the second paragraph of the DESCRIPTION, you can 
see too much space after “Nm.”  That happens in a few places.  
Another place is, on the same page, “( expr  )” as the first tag 
of the tagged list at the end.



(It still seems a little weird to me to follow `No` with `Ar`, but
having just embarrassed myself with my mdoc(7) inexpertise, I'll
withhold further opinion...)


Don’t worry, it would be weird to do that outside an example.

Re: Milestone reached: hyperlinked mdoc(7) documents in PDF

[G. Branden Robinson]

At 2024-03-18T13:00:19-0500, G. Branden Robinson wrote:
> At 2024-03-18T12:56:45-0500, G. Branden Robinson wrote:
> > It is not a goal of groff to behave identically to mandoc(1) in the
> > face of unspecified input.  Is your input specified somewhere?  (I
> > don't have the command of mdoc(7) that I do of man(7), and as we've
> > seen, my grasp of the latter is not flawless.)  Can you come up with
> > input that _is_ specified and yet still manifests this behavior?
> > 
> > And, yeah, I noticed the oblique face getting stuck on, too, when I
> > scrolled to the end of the document.
> 
> ...at the same time, this bad rendering doesn't happen with groff
> 1.22.4 or groff 1.23.0, so I might have inadvertently made groff
> mdoc(7) less robust here.  I'll bisect and see what I can see.

I was afraid of this.

df1fc139af57e947f038c52b3753dda411c3fc2e is the first bad commit
commit df1fc139af57e947f038c52b3753dda411c3fc2e
Author: G. Branden Robinson 
Date:   Sun Sep 3 20:58:42 2023 -0500

tmac/doc.tmac: Don't set `Ar` ellipsis in italics.

* tmac/doc.tmac (doc-str-Ar-default, Ar): Stop setting ellipsis in
  italics.

* tmac/groff_mdoc.7.man (Arguments): De-document apology for former
  behavior.

 ChangeLog |  7 +++
 tmac/doc.tmac |  4 ++--
 tmac/groff_mdoc.7.man | 11 ---
 3 files changed, 9 insertions(+), 13 deletions(-)

The wonderful thing about mdoc having its own macro processing system is
that it's so fragile.

diff --git a/tmac/doc.tmac b/tmac/doc.tmac
index 52ed73714..8bbcca8a7 100644
--- a/tmac/doc.tmac
+++ b/tmac/doc.tmac
@@ -789,7 +789,7 @@
 .\" NS
 .\" NS width register 'Ar' set in doc-common
 .
-.ds doc-str-Ar-default "file\ .\|.\|.
+.ds doc-str-Ar-default file \f[].\|.\|.\"
 .
 .eo
 .de Ar
@@ -802,7 +802,7 @@
 .
 .\" no argument
 .if !\n[.$] \
-.  nop \)\*[doc-str-Ar-default]\&\f[]
+.  nop \)\*[doc-str-Ar-default]\&
 .  \}
 .
 .  if !\n[doc-arg-count] \

Back to the drawing board.

Regards,
Branden


signature.asc
Description: PGP signature

Re: Milestone reached: hyperlinked mdoc(7) documents in PDF

[G. Branden Robinson]

At 2024-03-18T12:56:45-0500, G. Branden Robinson wrote:
> It is not a goal of groff to behave identically to mandoc(1) in the face
> of unspecified input.  Is your input specified somewhere?  (I don't have
> the command of mdoc(7) that I do of man(7), and as we've seen, my grasp
> of the latter is not flawless.)  Can you come up with input that _is_
> specified and yet still manifests this behavior?
> 
> And, yeah, I noticed the oblique face getting stuck on, too, when I
> scrolled to the end of the document.

...at the same time, this bad rendering doesn't happen with groff 1.22.4
or groff 1.23.0, so I might have inadvertently made groff mdoc(7) less
robust here.  I'll bisect and see what I can see.

Regards,
Branden


signature.asc
Description: PGP signature

Re: Milestone reached: hyperlinked mdoc(7) documents in PDF

[G. Branden Robinson]

Hi Lennart,

At 2024-03-18T02:08:10+, Lennart Jablonka wrote:
> .Dd March 18, 2024
> .Dt EMPTY-CALLED-AR
> .Os
> .Sh NAME
> .Nm empty-called-Ar
> .Nd a groff \-mdoc bug
> .Sh DESCRIPTION
> Empty called Ar:
> .No Ar
> That's it: This text right here shouldn't be oblique.
> .Pp
> I found this in your mandoc man page PDF in
> .Xr makewhatis 8 ,
> as
> .Bd -literal -offset indent
> \&.Fl t Ar
> .Ed

There may be some malformedness here complicating matters.

$ /usr/bin/nroff -mdoc EXPERIMENTS/lennart.mdoc # groff 1.22.4
mdoc warning: Using a macro as first argument cancels effect of .No (#9)
...
$ ~/groff-stable/bin/nroff -mdoc EXPERIMENTS/lennart.mdoc # groff 1.23.0
mdoc warning: Using a macro as first argument cancels effect of .No (#9)
...
$ ~/groff-HEAD/bin/nroff -mdoc EXPERIMENTS/lennart.mdoc
doc.tmac:EXPERIMENTS/lennart.mdoc:9: warning: using a macro as first argument 
cancels effect of .No

$ dpkg -l mandoc | tail -n 1
ii  mandoc 1.14.6-1 amd64BSD manpage compiler toolset

$ mandoc -Tlint EXPERIMENTS/lennart.mdoc
...
mandoc: EXPERIMENTS/lennart.mdoc:2:2: WARNING: missing manual section, using 
"": Dt EMPTY-CALLED-AR
...

...and in fact when I change line 9:

-.No Ar
+.No \

...the applicable warnings from groff mdoc _and_ mandoc go away, and the
text formats as you would expect.

It is not a goal of groff to behave identically to mandoc(1) in the face
of unspecified input.  Is your input specified somewhere?  (I don't have
the command of mdoc(7) that I do of man(7), and as we've seen, my grasp
of the latter is not flawless.)  Can you come up with input that _is_
specified and yet still manifests this behavior?

And, yeah, I noticed the oblique face getting stuck on, too, when I
scrolled to the end of the document.

It's possible this is an error in a mandoc man page.  Unthinkable?  ;-)

(That said, groff mdoc could do what some macro packages call a
"paragraph reset" more frequently, including restoration of the Times
[or default] family and roman style.  Doing so might align with other
ideas I have for typesetting mdoc(7) that I am afraid will [further]
scandalize наб.)

Regards,
Branden


signature.asc
Description: PGP signature

Re: Milestone reached: hyperlinked mdoc(7) documents in PDF

[Lennart Jablonka]

.Dd March 18, 2024
.Dt EMPTY-CALLED-AR
.Os
.Sh NAME
.Nm empty-called-Ar
.Nd a groff \-mdoc bug
.Sh DESCRIPTION
Empty called Ar:
.No Ar
That's it: This text right here shouldn't be oblique.
.Pp
I found this in your mandoc man page PDF in
.Xr makewhatis 8 ,
as
.Bd -literal -offset indent
\&.Fl t Ar
.Ed

Re: Milestone reached: hyperlinked mdoc(7) documents in PDF

[Alejandro Colomar]

Hi Branden!

On Sun, Mar 17, 2024 at 05:23:20PM -0500, G. Branden Robinson wrote:
> Hi folks,
> 
> Following up my earlier announcement regarding man(7),[1], I'm pleased
> to report that we have a functioning PDF hyperlink story for the mdoc
> package.
> 
> * The Mt macro hyperlinks email addresses.
> * The Lk macro hyperlinks general URLs.
> * The Xr macro produces "man:foo(1)"-style hyperlinks.
> 
> I've also refactored groff's "an.tmac" file sufficiently that the macro
> redefinitions that Deri contributed as part of the "doc/GMPfront.t"
> file[2] are no longer necessary.
> 
> The new GMPfront.t is smaller and more obviously performative of the
> straightforward business of formatting a cover page, so that other
> projects that want to collect their man pages into a PDF can use it as a
> model without being baffled by macro appendments and quadruply-escaped
> expressions.  Even better, because we are no longer appending to macros,
> the input line numbers are not made inaccurate in the event of
> diagnostic messages.[3]
> 
> Thus, if you build groff Git HEAD from source, the generated
> groff-man-pages.pdf is now internally linked between not only all the
> man(7) format pages, but the mdoc(7) one as well.
> 
> A copy is available at the usual Dropbox, of course.
> 
> https://www.dropbox.com/sh/17ftu3z31couf07/AAC_9kq0ZA-Ra2ZhmZFWlLuva?dl=0
> 
> As a further demonstration, and as a gift (bone?) to mdoc(7) mavens, I'm
> attaching a PDF of all the mandoc(1) man pages, along with the 2-line
> shell script I used to produce it.
> 
> I welcome feedback, as always.  And bug reports.
> 
> Regards,
> Branden
> 
> P.S. Alex, you might want to consider simplifying your cover page
>  similarly once you bring your copy of groff up to date.

How much would you consider having a release sooner than expected, and
then have what originally would have been 1.24.0 be 1.25.0?  :)

I would prefer using a packaged version of groff, for two reasons:

-  I got impedance mismatches, when I see stuff like the 5n base-
   paragraph indent, but contributors are still seeing 7n.

-  In my server, I have a script that builds the man-pages book for
   every push to the main branch (true for both the Linux man-pages and
   shadow), and another that runs the lints and checks for the Linux
   man-pages.  Having built-from-source software in my computer is less
   of a problem, but in a server, it's less comfortable.  (I already
   have Deri's branch in there, and I'm not in love with that.)

But yeah, I'm willing to simplify as much as possible!  ;)

Cheers,
Alex

> https://git.savannah.gnu.org/cgit/groff.git/tree/doc/GMPfront.t.in
> 
> [1] https://lists.gnu.org/archive/html/groff/2024-01/msg00125.html
> 
> [2] ...now generated from "doc/GMPfront.t.in" at build time, so that the
> cover page can include the groff version number without requiring
> manual maintenance.
> 
> [3] This is a long-standing deficiency of GNU troff.  Would take some
> doing to solve, I think; the whole concept of a line number could no
> longer be expressed as an integer, but would instead require a
> structured object of some kind.  Possibly a recursively structured
> object at that, since `am` requests could occur inside portions of
> macros that were themselves populated by `am`...


> sed -i -e 
> '/^\.Dt/{s/Dt/99/;y/ABCDEFGHIJKLMNOPQRSTUVWXYZ/abcdefghijklmnopqrstuvwxyz/;s/99/Dt/;}'
>  *.[1-8]
> for s in 1 3 5 7 8; do echo *.$s; done | xargs groff -t -mdoc -Tpdf >| 
> mandoc-groffed.pdf




-- 

Looking for a remote C programming job at the moment.


signature.asc
Description: PGP signature