bugGNU roff - Bugs: bug #62551, [PATCH] doc/groff.texi: Fix...

 
 

bug #62551: [PATCH] doc/groff.texi: Fix content and style nits

Submitter:  Dave <barx>
Submitted:  Tue 31 May 2022 06:24:11 PM UTC
   
 
Category:  Core Severity:  2 - Minor
Item Group:  Documentation Status:  Fixed
Privacy:  Public Assigned to:  gbranden
Open/Closed:  Closed Planned Release:  1.23.0
* Mandatory Fields

Add a New Comment Rich Markup
   

Jump to the original submission

Mon 06 Jun 2022 08:58:17 PM UTC, comment #13: 

TeX dependency now spun off into bug #62592 so we don't have to keep hijacking this one.

Dave <barx>
Group Member
Sun 05 Jun 2022 09:41:16 PM UTC, comment #12: 

Discussion of TeX dependency continued at http://lists.gnu.org/r/groff/2022-06/msg00013.html

Dave <barx>
Group Member
Sat 04 Jun 2022 04:19:14 PM UTC, comment #11: 

Hi Deri!

comment #10:

> Is it true that previously you didn't need a full TeX installation to build groff from git, it just did not build groff.pdf as part of the process.


Yes, that's correct.

> Now it seems the build borks very early on if tex2dvi is not found, so you have to have the majority of TeX installed (it's very big!) to get a runniable groff. Is this change intentional/desirable?


Intentional, yes.  Desirable...well, maybe not.

Ingo and I have done a ton of work on the build system over the past couple of months, to simplify it and reduce the number of build scenarios that need to be tested.  This one was probably the main commit in question.


commit 3805d2a0e4aebb84d896f86285fd565488e849bb
Author: Ingo Schwarze <schwarze@openbsd.org>
Date:   Tue Apr 12 14:36:12 2022 +0200

    [configure] Delete the --with-doc option.

    This option was harmful, ill-designed, buggy, and essentially
    unmaintained and untested.  For more details on the rationale,
    see the NEWS file.

    OK gbranden@ and no objection when shown on groff at gnu dot org.


I'm not exactly happy with adding a build-dep on TeX for Git users.  But some big dividends have been paid for the build-from-distribution-archive scenario, which I (and I think Ingo) regard as more important for getting a release out on the door.

That said, I've spent enough time on the build system over the past 2 months that I am confident that I understand how to make the build skip generation of groff.{dvi,pdf} if TeX is not installed.  That would involve less machinery than the erstwhile '--with-doc' option.

> Sorry, probably not the right place to ask this question.


It's fine!  But you might want to raise it on groff@gnu for further discussion.

If you do, I expect the notion of getting rid of our Texinfo manual, or converting it to a groff input document, will be mooted.  I would oppose the former--there's too much good information in it that isn't suitable for man pages to just throw it away.

For the latter, there is the semi-automated(?) conversion work you have shared more than once, but I admit I haven't taken a look at it recently.  :(  I have no good reason for that apart from simply "not having enough spoons", as the saying goes.

G. Branden Robinson <gbranden>
Group administrator
Sat 04 Jun 2022 11:44:57 AM UTC, comment #10: 

Is it true that previously you didn't need a full TeX installation to build groff from git, it just did not build groff.pdf as part of the process. Now it seems the build borks very early on if tex2dvi is not found, so you have to have the majority of TeX installed (it's very big!) to get a runniable groff. Is this change intentional/desirable?

Sorry, probably not the right place to ask this question.

Deri James <deri>
Group Member
Fri 03 Jun 2022 10:15:29 PM UTC, comment #9: 

comment #8:

> But I was suggesting that maybe your TeX installation got
> messed up somehow.


Possible.  I never use TeX directly; it's only on my system as a prereq for another package that I used to use but no longer really do, so I have little incentive to track down and fix problems with it.

> More information would be good.


I'll provide whatever info you think is helpful, but as neither of us are TeX people, I'm not sure what that would be, and not sure a closed bug report for an unrelated problem is the best venue.

In any event, we both seem to think the probability of this being a groff problem is low.

Dave <barx>
Group Member
Wed 01 Jun 2022 07:34:59 PM UTC, comment #8: 


comment #7:

> OK.  If we're correct, it's a little concerning that a TeX from a mere two years ago can now prevent a successful groff build.


If that's the case, then I'm concerned, too.  On the bright side, building from the distribution archive won't see this problem, because doc/groff.{dvi,pdf} are already present in it.

>  But I suppose if the problem is widespread we'll hear more about it when rc2 hits the streets.


If people build straight from Git, yes.

But I was suggesting that maybe your TeX installation got messed up somehow.

Another possibility is that your installed version of Texinfo is exercising some fairly recent feature of your TeX distribution.  This seems unlikely to me, though.

It's worth noting that groff doesn't depend on TeX directly, but only via the 'texi2dvi' command.

More information would be good.  I've got successful builds going in a Debian bullseye chroot with the following version of Tex Live.


$ dpkg -l texlive
Desired=Unknown/Install/Remove/Purge/Hold
| Status=Not/Inst/Conf-files/Unpacked/halF-conf/Half-inst/trig-aWait/Trig-pend
|/ Err?=(none)/Reinst-required (Status,Err: uppercase=bad)
||/ Name           Version         Architecture Description
+++-==============-===============-============-=====================================================
ii  texlive        2020.20210202-3 all          TeX Live: A decent selection of the TeX Live packages


G. Branden Robinson <gbranden>
Group administrator
Wed 01 Jun 2022 06:47:47 PM UTC, comment #7: 

OK.  If we're correct, it's a little concerning that a TeX from a mere two years ago can now prevent a successful groff build.  But I suppose if the problem is widespread we'll hear more about it when rc2 hits the streets.

Dave <barx>
Group Member
Wed 01 Jun 2022 05:53:45 PM UTC, comment #6: 


comment #5:

> comment #3:
> > It should these days!  Or, rather, it will if you have the
> > requisite tools installed.
>
> I think I fell into the cracks of the timeline.  I last built on April 23, just before commit c21f1a0e.  I can't tell from the commit log whether this is the commit that pulled the plug on "make doc" -- it updated NEWS to that effect, but it's characterized at the top as a refactor, which to me implies no functionality change.


I may have abused the term.  I remember thinking after Ingo's commit that "make doc" should now do nothing, but I have no clear memory of testing that.

> This commit was a follow-on to Ingo's commit 3805d2a0, which was in the tree I built, so maybe I was supposed to get these files with an unadorned "make"?  Anyway, I won't consider this a bug until I've built with all the latest changes and see what happens then.


Yes.  If building from Git you definitely should get groff.dvi and groff.pdf.  This is a consequence of Ingo's commit.

> > What happens when you cd into your build directory (a no-op
> > if you build in the source tree) and say
> >


> > make groff.dvi
> > make groff.pdf


> >
> > ?
>
> If I do that literally, I get "No rule to make target 'groff.dvi'.  Stop."  But if I do what I deduce you meant, "make doc/groff.pdf", I get... a couple thousand lines of errors and a build failure. \-:  None of this was output when I built the rest of groff, so (at least as of a month and a half ago) a simple "make" did not attempt to run this step.


Yes, that's what I meant.  "make doc/groff.{dvi,[df}".  baghead

And yes.  Suddenly the groff infrastructure is more aggressive about trying to build those files.  In fact the only way to stop it without altering the Makefiles is to fake it out (possibly with dummy target files).

> The errors appear to be related to outdated TeX tools, so also are not something I think groff need be concerned with.  A huge number of the lines are repetitions of:


> kpathsea: Running mktextfm lcircle10
> /usr/share/texmf-dist/web2c/mktexnam: Could not map source abbreviation  for lcircle10.
> /usr/share/texmf-dist/web2c/mktexnam: Need to update ?
> mktextfm: Running mf-nowin -progname=mf \mode:=ljfour; mag:=1; ; nonstopmode; input lcircle10
> This is METAFONT, Version 2.7182818 (TeX Live 2020 Gentoo Linux) (preloaded base=mf)
>
>
> kpathsea: Running mktexmf lcircle10
> ! I can't find file `lcircle10'.
> <*> ...our; mag:=1; ; nonstopmode; input lcircle10
>
> Please type another input file name
> ! Emergency stop.
> <*> ...our; mag:=1; ; nonstopmode; input lcircle10
>
> Transcript written on mfput.log.
> grep: lcircle10.log: No such file or directory
> mktextfm: `mf-nowin -progname=mf \mode:=ljfour; mag:=1; ; nonstopmode; input lcircle10' failed to make lcircle10.tfm.
> kpathsea: Appending font creation commands to missfont.log.


Yes, the foregoing is far beyond my ken.  This is why they have the word "TeXpert".

But I'm guessing you're right--probably a package upgrade or, at worst, reinstall of your TeX distribution will clear it up.

G. Branden Robinson <gbranden>
Group administrator
Wed 01 Jun 2022 05:44:01 PM UTC, comment #5: 

comment #3:

> It should these days!  Or, rather, it will if you have the
> requisite tools installed.


I think I fell into the cracks of the timeline.  I last built on April 23, just before commit c21f1a0e.  I can't tell from the commit log whether this is the commit that pulled the plug on "make doc" -- it updated NEWS to that effect, but it's characterized at the top as a refactor, which to me implies no functionality change.  This commit was a follow-on to Ingo's commit 3805d2a0, which was in the tree I built, so maybe I was supposed to get these files with an unadorned "make"?  Anyway, I won't consider this a bug until I've built with all the latest changes and see what happens then.

> What happens when you cd into your build directory (a no-op
> if you build in the source tree) and say
>


> make groff.dvi
> make groff.pdf


>
> ?


If I do that literally, I get "No rule to make target 'groff.dvi'.  Stop."  But if I do what I deduce you meant, "make doc/groff.pdf", I get... a couple thousand lines of errors and a build failure. \-:  None of this was output when I built the rest of groff, so (at least as of a month and a half ago) a simple "make" did not attempt to run this step.

The errors appear to be related to outdated TeX tools, so also are not something I think groff need be concerned with.  A huge number of the lines are repetitions of:

kpathsea: Running mktextfm lcircle10
/usr/share/texmf-dist/web2c/mktexnam: Could not map source abbreviation  for lcircle10.
/usr/share/texmf-dist/web2c/mktexnam: Need to update ?
mktextfm: Running mf-nowin -progname=mf \mode:=ljfour; mag:=1; ; nonstopmode; input lcircle10
This is METAFONT, Version 2.7182818 (TeX Live 2020 Gentoo Linux) (preloaded base=mf)


kpathsea: Running mktexmf lcircle10
! I can't find file `lcircle10'.
<*> ...our; mag:=1; ; nonstopmode; input lcircle10

Please type another input file name
! Emergency stop.
<*> ...our; mag:=1; ; nonstopmode; input lcircle10

Transcript written on mfput.log.
grep: lcircle10.log: No such file or directory
mktextfm: `mf-nowin -progname=mf \mode:=ljfour; mag:=1; ; nonstopmode; input lcircle10' failed to make lcircle10.tfm.
kpathsea: Appending font creation commands to missfont.log.


Dave <barx>
Group Member
Wed 01 Jun 2022 12:36:09 AM UTC, comment #4: 


commit e30fe480b4af3b3725d19af20fd9093185f07818
Author: Dave Kemper <saint.snit@gmail.com>
Date:   Tue May 31 18:24:11 2022 +0000

    doc/groff.texi: Fix content and style nits.

    * Remove redundancy ("fixed-width... character that can't be adjusted").
    * Fix incorrect word ("environment value" -> "environment variable").
    * Add or change the placement of a couple tie{}s to comport with
      style-guide recommendation.
    * Grammarify.
    * Clarify and tighten wording.

    Fixes <https://savannah.gnu.org/bugs/?62551>.


G. Branden Robinson <gbranden>
Group administrator
Wed 01 Jun 2022 12:08:10 AM UTC, comment #3: 


comment #2:

> I see.  I guess a standard build doesn't generate the PDF version (or it hides it well).


It should these days!  Or, rather, it will if you have the requisite tools installed.

What happens when you cd into your build directory (a no-op if you build in the source tree) and say


make groff.dvi
make groff.pdf


?

> To be fair, I had a list of minor Texinfo stuff to fix "someday" that I've been collecting for a while, and when I went to finally make the changes and generate a patch, about half the items on my list had been fixed already.


There is no rest for the nitpicky.

G. Branden Robinson <gbranden>
Group administrator
Tue 31 May 2022 11:36:43 PM UTC, comment #2: 

comment #1:

> Cover page material seems only to appear in DVI and PDF output,


I see.  I guess a standard build doesn't generate the PDF version (or it hides it well).

> As you probably saw, Trent's name does appear in an example in the
> manual, but as unfilled text, so a tie would be superfluous there.


Yup, that matches my conclusion upon finding that.

> Good stuff here, including fixes for some errors I think I introduced.


To be fair, I had a list of minor Texinfo stuff to fix "someday" that I've been collecting for a while, and when I went to finally make the changes and generate a patch, about half the items on my list had been fixed already.

Dave <barx>
Group Member
Tue 31 May 2022 08:39:44 PM UTC, comment #1: 

Thanks, Dave!

original submission:

> Possible controversial points about this patch:
>
> * In a couple cases I removed what I consider to be excess verbiage; if you feel any removed wording removes useful information, feel free to excise that part of the patch.
>
> * The Chicago Manual of Style (see the answer to the first question on http://www.chicagomanualofstyle.org/qanda/data/faq/topics/WordDivision.html) says it is "advisable to avoid a break... before (but not after) a middle initial."  This is the opposite of what was being done with the names Trent A. Fisher and Eric P. Allman.  The name J. F. Ossanna did follow CMOS style here.
>
> CMOS is not universally accepted, but I can also justify this styling on purely typographic grounds if necessary (but I won't bore you if not).


I'm okay with it.  I have a voodoo doll of Russell Harper but that doesn't mean I think CMOS is categorically wrong.
 

> The name Jerome H. Saltzer had no tie{}, and I have not added one, presuming its omission was intentional based on the name's placement on the line.  (However, one could also argue for marking up names consistently as a defensive measure.)


The whole "History" node/section is going away in a pending commit anyway--for once, we got lucky and didn't end up hacking on the same parts of our Texinfo manual simultaneously.  :)
 

> The name M. E. Lesk had no tie{}.  I added one, presuming this was an oversight, but it's possible this was also intentional (the name appears inside a cite{}, if that matters).  This change can also be omitted if it serves no purpose.


As far as I know, the Texinfo @cite command has no impact on text flow or layout.  (My knowledge of Texinfo is shallow, however.)

> Trent's name appears in the manual's list of authors, and I can't find where the author list (or any of the titlepage information) is actually displayed, either through the info(1) interface, or in the groff.txt file generated by the build.  So the placement of this tie{} may make no real-world difference.


Cover page material seems only to appear in DVI and PDF output, so, no, I guess it doesn't make any difference.  It's conceivable that a future Texinfo may include these data in other output formats, and since it's anyone's guess what layout may eventuate, the conservative approach of adding the tie seems prudent to me.

As you probably saw, Trent's name does appear in an example in the manual, but as unfilled text, so a tie would be superfluous there.

Good stuff here, including fixes for some errors I think I introduced.  Thank you!

G. Branden Robinson <gbranden>
Group administrator
Tue 31 May 2022 06:24:11 PM UTC, original submission:  

What this patch does:


    doc/groff.texi: Fix content and style nits.

    * Remove redundancy ("fixed-width... character that can't be adjusted")
    * Fix incorrect word ("environment value" -> "environment variable")
    * Add or change the placement of a couple tie{}s to comport with
      style-guide recommendation
    * Grammarify
    * Clarify and tighten wording


Possible controversial points about this patch:

  • In a couple cases I removed what I consider to be excess verbiage; if you feel any removed wording removes useful information, feel free to excise that part of the patch.


  • The Chicago Manual of Style (see the answer to the first question on http://www.chicagomanualofstyle.org/qanda/data/faq/topics/WordDivision.html) says it is "advisable to avoid a break... before (but not after) a middle initial."  This is the opposite of what was being done with the names Trent A. Fisher and Eric P. Allman.  The name J. F. Ossanna did follow CMOS style here.


CMOS is not universally accepted, but I can also justify this styling on purely typographic grounds if necessary (but I won't bore you if not).

The name Jerome H. Saltzer had no tie{}, and I have not added one, presuming its omission was intentional based on the name's placement on the line.  (However, one could also argue for marking up names consistently as a defensive measure.)

The name M. E. Lesk had no tie{}.  I added one, presuming this was an oversight, but it's possible this was also intentional (the name appears inside a cite{}, if that matters).  This change can also be omitted if it serves no purpose.

Trent's name appears in the manual's list of authors, and I can't find where the author list (or any of the titlepage information) is actually displayed, either through the info(1) interface, or in the groff.txt file generated by the build.  So the placement of this tie{} may make no real-world difference.

Dave <barx>
Group Member

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

Attached Files
file #53263:  texinfo.patch added by barx (8KiB - text/x-patch)

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by deri (Posted a comment)
  • -email is unavailable- added by gbranden (Posted a comment)
  • -email is unavailable- added by barx (Submitted the item)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only logged-in users can vote.

     

    Follow 6 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2022-06-01 gbranden StatusIn Progress Fixed
        Open/ClosedOpen Closed
        Planned ReleaseNone 1.23.0
    2022-05-31 gbranden StatusNone In Progress
        Assigned toNone gbranden
    2022-05-31 barx Attached File- Added texinfo.patch, #53263

    Back to the top

    Powered by Savane 3.13-02a9.
    Corresponding source code