Re: [PATCH v2] man*/: ffix (migrate to `MR`)

[Alejandro Colomar]

Hi Branden,

On 2023-08-16 05:55, G. Branden Robinson wrote:
[...]

>> Would you mind sending an updated commit message?
> 
> I did, but you found a fresh problem, this time with part 1, so I guess
> we'll be going to v4!  :-O  Also I'm going to make an attempt to drive
> the part 1 change with sed as well.  Just to see if I can, and to see
> what happens.

Great!  (As long as it's kept as a separate patch.  ;)

> 
>> Heh, I noticed some weirdness about it, but it happened to be after a
>> -rCHECKSTYLE, so it seemed like it could be some improvements that you
>> had applied upstream to CHECKSTYLE.  =3 definitely made sense to that
>> register.
> 
> GNU troff(1) does not raise a diagnostic if a register assignment is
> followed by garbage.  That's disappointing.
> 
> Filed.  https://savannah.gnu.org/bugs/?64559

Nice.

> 
>>> Please double-check for that before pushing to kernel.org.
>>
>> Please send one that I don't need to modify.  I don't like modifying
>> other's stuff, in case I break it.  :)
> 
> Did v3 2/2 show up for you without quoted-printable damage?

Yup.  I assume Thunderbird is not messing with the source of
the received email.  I bet it's neomutt(1), even if I'd expect
it's not the kind of program that would do that.

Please send a hand-crafted encrypted copy in an attached file,
where no program can mess with it.

> 
>> and against man-pages(7) recommendations.

 Well, we should update those to use MR.
>>>
>>> And man(7) too, I guess.  What do you think?
>>
>> I want to kill that page.  Please have a look at it, take anything
>> good that it has for groff_man{,_style}(7), and ping me when I
>> should sharpen the scythe.  ;)
> 
> Ok, will do.
> 
> If the page is withdrawn, I expect distributors will need to manage the
> man.7 page using Debian's "alternatives" mechanism or similar; if
> groff_man.7 is installed, man.7 should be a symlink to it.  If
> mandoc_man.7 is installed, likewise.  If both are installed, the
> distributor needs to select a default preference.
> 
> I expect you will want to emphasize this in the release announcement,
> when the time comes.

Sure.  6.6 will be a big release.  Maybe there are many bug-fix patches
to it...  like 6?

> 
> This already needs to happen with soelim(1) and roff(7), but it doesn't,
> exactly; Debian renames mandoc's versions of the former to msoelim(1)
> and the latter to mandoc_roff(1).  Termux simply throws groff's versions
> away and installs mandoc's versions as soelim(1) and roff(7).
> 
> I also use Termux.

This reminds me I need to ping for the replacement of my Linux phone,
which has issues, and I can't receive calls.  :|

>  Imagine my surprise when I upgraded to groff 1.23.0
> on my tablet and brought up roff(7).  I was expecting to see myself in
> the mirror, and what should greet me but the visage of Ingo Schwarze!

Huh!  Under what criteria do they choose mandoc_roff(7) as /the/ roff(7)?

> 
> Unnerving, no?

It is!

Cheers,
Alex

> 
> Regards,
> Branden

-- 

GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5



OpenPGP_signature
Description: OpenPGP digital signature

Re: Anyone want to write an article about fonts in groff?

[Walter Alejandro Iglesias]

Hi Jim,

On Sat, Aug 12, 2023 at 03:48:21PM -0500, Jim Hall wrote:
> Hi everyone!
> 
> I was thinking about writing a few articles for Technically We Write
> about fonts in groff. But I thought "This would be a great article for
> someone else to write" so I wanted to suggest it here.
> 
> Here are two article ideas:
> 
> 1. An article about how fonts work in groff (each is "mounted" to a
> different font "position" number) and showing how to use different
> fonts in a groff document. For example, to mount Helvetica Narrow
> (HNR) to font position 5 (I think that's unused in -me) and set the
> .sh and .uh fonts in -me to that:
> 
> .fp 5 HNR
> .nr sf 5
> 
> 2. How to convert a TrueType font and use them in groff documents. I
> found this how-to article that seems to explain it pretty well, but I
> haven't tried it yet:
> 
> http://www.port.de/cgi-bin/groff/AddingFonts
> 
> 
> If anyone is interested in writing an article like this, let me know!


What I'll tell you could be useful to whoever decide to write the
article, but not in the sense of simplifying the process, quite the
opposite :-).

About your second point, I recently wrote this:

  http://en.roquesor.com/groff.html

What I observed and didn't mention in my article is that adding .t42
files to the devps directory (and the entries to the devps/downloads
file) the result is better than putting there .pfa files.  And also
that, at least with EBGaramond and other OFT and TTF fonts I tried,
you need to include these files, without them, the result font shows
wrong glyphs, the line width won't be correctly adjusted, and the main
one: the font will look almost +5 points bigger than without adding the
.t42 files.

After reading Petrovic's article I got curious about if using pdftex's
utilities I could get the same result than using fontforge so, to narrow
the differences, I added the mentioned two steps to Petkovic's tutorial;
besides ttf2afm, I used ttftotype42 to add the *.42 files to the devps
directory and also added the entries to the downloads file.  This time,
the result was at first sight identical, but when I reviewed my document
in detail I noticed that, by an almost imperceptible tiny difference,
lines didn't take the same amount of width space generating erratic
widows and orphans.  This is a point to take in care, once you've found
a method that works for you case don't change it :-).


> 
> 
> Jim
> 
> 


-- 
Walter

Re: [PATCH v2] man*/: ffix (migrate to `MR`)

[Ingo Schwarze]

Hi Branden,

G. Branden Robinson wrote on Tue, Aug 15, 2023 at 10:55:22PM -0500:

> If the page is withdrawn, I expect distributors will need to manage the
> man.7 page using Debian's "alternatives" mechanism or similar; if
> groff_man.7 is installed, man.7 should be a symlink to it.  If
> mandoc_man.7 is installed, likewise.  If both are installed, the
> distributor needs to select a default preference.

I think that most general-purpose Linux distributions are probably
better off simply prefering groff_man.7 over the man.7 bundled with
mandoc.  As you know, the mandoc distribution regards the man(7)
language as a legacy language that is obsolete since about 1990 -
which makes sense for all operating systems based on BSD and Illumos.
Consequently, the mandoc man(7) page only provides bare-bone information
focussing on questions of compatibily and no advice whatsoever
for people intending to write new manual pages.

That perspective is not really helpful for general purpose Linux
distributions: for these, the Linux man-pages project matters a lot,
and that project is not considering the man(7) language as obsolete at
all.  That i keep recommending changing that stance does not appear to
have much effect so far and isn't relevant for the questions at hand.
Either war, a disagreement regarding the merits of some policy is
not a good reason to deprive users of information they might require.

> I expect you will want to emphasize this in the release announcement,
> when the time comes.

In the Linux man-pages project release announcement, i recommend
simply saying that groff_man(7) replaces the former man(7) that used
to be bundled in the Linux man-pages project.  For the purposes of
the Linux man-pages project, the man(7) page distributed with mandoc
isn't useful, so no need to confuse the users of the Linux man-pages
project by talking about it.

> This already needs to happen with soelim(1) and roff(7),

I'm not convinced.  The soelim(1) bundled with mandoc is
really only a stopgap implementation in case people need something
quickly but don't have a real ROFF system around.  I don't think
it sees much use at all.

For the roff(7) manual page bundled with mandoc, the same applies
as for man(7), only more strongly so.  The mandoc roff(7) page is
totally inadequate for learning the roff language.  It merely
intends to document the subset of roff(7) relevant for manual
page authors and maintainers, and the subset supported by mandoc.

> but it doesn't, exactly; Debian renames mandoc's versions of the
> former to msoelim(1) and the latter to mandoc_roff(1).

That makes sense to me, more than using "alternatives" for these two
would, in the case of Debian.  I'm not sure installing the mandoc
soelim program on Debian is even useful in the first place.  If you
really need soelim(1) on Debian, you almost certainly already have
groff(1) installed, or at least you ought to install it.

> Termux simply throws groff's versions
> away and installs mandoc's versions as soelim(1) and roff(7).

That also makes some sense to me.  In Termux, the complete
subsystem for searching, displaying, and viewing manual pages has
been exclusively based on mandoc since 2015.  So while Termux is, in
most aspects, more similar to a Linux distro than to a BSD system,
regarding documentation, it is essentially a BSD and not a Linux
system, so it totally makes sense to follow BSD conventions regarding
manual page naming, installation, and manual page tools.

Besides, it is a system for relatively small devices, and consequently,
the decision to use BSD tools for documentation actually makes
sense because the mandoc toolchain is significantly less resource-
hungry than the groff toolchain.  Of course, mandoc is inadequate
for general-purpose typographic and publishing work - but who in
their right mind would want to write their books and journal
articles on Termux anyway?

A small number of other Linux systems exist where similar arguments
apply, most notably Alpine Linux and Void Linux.  Alpine is heavily
geared towards very small hardware.  Void is among the Linux distros
closest to BSD in philosophy.  Both have been using mandoc exclusively
for even longer than Termux.

But even for Linux distros officially supporting that users switch
their manual page search and display system from man-db+groff to
mandoc if they want to - last time i looked, that included Arch,
openSUSE, and Fedora - installing the mandoc roff(7) as roff(7)
would seem like a bad idea to me.

> I also use Termux.  Imagine my surprise when I upgraded to groff 1.23.0
> on my tablet and brought up roff(7).  I was expecting to see myself in
> the mirror, and what should greet me but the visage of Ingo Schwarze!
> 
> Unnerving, no?

Heh, buhuuu!  

Yours,
  Ingo

QR codes in pic

[Alexis]

Hello everyone,

those using QR codes in their documents prepared with GNU troff, might
welcome a PR¹ for libqrencode, that adds support to generate QR codes
drawn with pic(1).

Libqrencode hasn't seen a release in quite some time and seems dormant;
if you find the work interesting and have a GitHub account, stating your
interest on the PR might help in getting it merged and a new release out.


Best
Alexis

¹ https://github.com/fukuchi/libqrencode/pull/208

Re: [PATCH v2] man*/: ffix (migrate to `MR`)

[Alejandro Colomar]

Hi Ingo!

On 2023-08-16 18:33, Ingo Schwarze wrote:
> That perspective is not really helpful for general purpose Linux
> distributions: for these, the Linux man-pages project matters a lot,
> and that project is not considering the man(7) language as obsolete at
> all.  That i keep recommending changing that stance does not appear to
> have much effect so far

It does have an effect, or I like to think it has.  Branden and I are
pushing to improve man(7) to be on par with mdoc(7) where it's lacking.

I also recently added support for mdoc(7) in the build system, so new
mdoc(7) pages will enjoy the same linting level to which I subject our
existing man(7) pages.  If anyone wants to write new pages using
mdoc(7), they're welcome.  I'm not going to require man(7) (but I
prefer it for my own pages).





So, if anyone wants to add a page that's not present, and decides to
write it using mdoc(7), it'll be welcome.  That includes the suggestion
of a new intro.1, which IIRC was written in mdoc(7).  I should revise
that page.  I lack experience using it, but I guess I'll learn more
with enough time.

Also, if anyone wants to fork this project and rewrite it using mdoc(7),
or maybe use it for having a documentation repo of whatever project,
I made it easy to do so.  (In fact, I added mdoc(7) support for linting
an mdoc(7) page at my job.)

I even plan to add support for mm(7) pages, if POSIX deigns to talk to
me to provide their sources.

> and isn't relevant for the questions at hand.
> Either war, a disagreement regarding the merits of some policy is
> not a good reason to deprive users of information they might require.
> 
>> I expect you will want to emphasize this in the release announcement,
>> when the time comes.
> 
> In the Linux man-pages project release announcement, i recommend
> simply saying that groff_man(7) replaces the former man(7) that used
> to be bundled in the Linux man-pages project.  For the purposes of
> the Linux man-pages project, the man(7) page distributed with mandoc
> isn't useful, so no need to confuse the users of the Linux man-pages
> project by talking about it.

I'll probably have a few suggestions of how it could works, so that
every distro understands what to do (even the small ones), but yeah,
I'll keep it simple for the generic case, and suggest that most
distros probably want to have a symlink from man(7) to groff_man(7).

> 

[...]

>> Unnerving, no?
> 
> Heh, buhuuu!  

:-}

Do you have in your plans to add support for MR?  That's probably a
blocker for applying Branden's patch in the master branch.

Cheers,
Alex

> 
> Yours,
>   Ingo

-- 

GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5



OpenPGP_signature
Description: OpenPGP digital signature

linting mdoc(7) pages (was: [PATCH v2] man*/: ffix (migrate to `MR`))

[Alejandro Colomar]

Hi Ingo!

On 2023-08-16 20:25, Alejandro Colomar wrote:
> Hi Ingo!
> 
> On 2023-08-16 18:33, Ingo Schwarze wrote:
>> That perspective is not really helpful for general purpose Linux
>> distributions: for these, the Linux man-pages project matters a lot,
>> and that project is not considering the man(7) language as obsolete at
>> all.  That i keep recommending changing that stance does not appear to
>> have much effect so far
> 
> It does have an effect, or I like to think it has.  Branden and I are
> pushing to improve man(7) to be on par with mdoc(7) where it's lacking.
> 
> I also recently added support for mdoc(7) in the build system, so new
> mdoc(7) pages will enjoy the same linting level to which I subject our
> existing man(7) pages.  If anyone wants to write new pages using
> mdoc(7), they're welcome.  I'm not going to require man(7) (but I
> prefer it for my own pages).
> 
> 
> 
> 
> 
> So, if anyone wants to add a page that's not present, and decides to
> write it using mdoc(7), it'll be welcome.  That includes the suggestion
> of a new intro.1, which IIRC was written in mdoc(7).  I should revise
> that page.  I lack experience using it, but I guess I'll learn more
> with enough time.
> 
> Also, if anyone wants to fork this project and rewrite it using mdoc(7),
> or maybe use it for having a documentation repo of whatever project,
> I made it easy to do so.  (In fact, I added mdoc(7) support for linting
> an mdoc(7) page at my job.)
> 
> I even plan to add support for mm(7) pages, if POSIX deigns to talk to
> me to provide their sources.

BTW, I remember you showed interest in the ability to lint all pages.
You may be interested in trying this:

$ make lint-mdoc MANDIR=/home/alx/src/bsd/openbsd/src -k

You may really use anything as MANDIR, and you may also use different
targets, but lint-mdoc will run mandoc(1) as the linter, which I guess is
the most interesting one to you.  Check `make help` for that.

You may need to adjust a few command variables to use the gnu variants,
as I doubt I write portable stuff.  Ye be warned.  Check
`make help-variables` for that.

If you try this, you'll need the very latest commit, as I just fixed
a bug in a script that misinterpreted some pathname in the OpenBSD tree.

Cheers,
Alex

-- 

GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5



OpenPGP_signature
Description: OpenPGP digital signature