bugGNU roff - Bugs: bug #60929, device man pages should...

 
 

bug #60929: device man pages should consistently document font repertoire

Submitter:  T. Kurt Bond <tkurtbond>
Submitted:  Sat 17 Jul 2021 12:00:31 AM UTC
   
 
Category:  Driver - others/general Severity:  3 - Normal
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
   

Fri 28 Oct 2022 10:32:23 PM UTC, comment #4: 

Turns out that 6 October commit was the last one necessary.  I'll add a bug-closer ChangeLog entry for it.

G. Branden Robinson <gbranden>
Group administrator
Thu 06 Oct 2022 01:28:18 PM UTC, comment #3: 


commit 68f83c358b8bed65662cadcd31e867ce627eed32
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Thu Oct 6 05:58:44 2022 -0500

    grolj4(1): Document available typefaces.

    * src/devices/grolj4/grolj4.1.man (Typefaces): Add new subsection.


(grolbp(1) already has adequate coverage of typefaces.)

G. Branden Robinson <gbranden>
Group administrator
Mon 22 Aug 2022 12:24:21 PM UTC, comment #2: 

I am lazy and chewing through these in lexicographic order.

Here's some stuff pending in my working copy.


commit d68aec06c6770e2c16fc331fcee71d612d71263d
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Sun Aug 21 07:20:11 2022 -0500

    grodvi(1): Organize and clarify.

    Impose more structure on output driver man pages (1/x).

    Fix content nits.
    * Discuss "interpretation" of DVI more, and "printing" less.
    * Migrate terminology: (troff) "commands" -> "escape sequences".
    * Apply terminology: (nothing) -> (troff) "escape sequences".
    * Apply terminology: "command" -> "device control" (escape sequence).
    * Migrate terminology: "drawing color" -> "stroke color".
    * Drop "Usage" section heading in favor of subsections "Typefaces",
      "Font description files", and "Drawing commands".
    * Align discussion of groff styles with grotty(1).
    * Explain "CM" abbreviation.
    * Clarify what's going on with "TR", "TI", and "CW" fonts being special
      for this output device.
    * Migrate terminology: macro files are "loaded", not "called".
    * Migrate terminology: "current position" -> "drawing position".  We
      have our own lexicon and it is not PostScript's.
    * Clarify what dvi.tmac does.

    Fix style nits.
    * Set "Name" section's summary-description terms in italics as needed.
    * Identify troff macro names without leading dot.
    * Recast sentence fragments to eliminate dangling colons.
    * Use active voice and imperative mood to instruct the user in the
      creation of font description files for groff.
    * Say "design size" in prose.
    * Discuss behavior of 'R' drawing command in present tense, not future.
    * Put a space between "-F' option and its argument when presenting it.
    * (Environment) Begin sentences with the paragraph tag, to economize and
      align with section "Files".
    * Use English thousands separator in large magnitude in prose.
    * Set off long restrictive adverbial phrase with commas on both sides.
    * Tighten wording.

    Fix markup nits.
    * Prevent hyphenation of font description file directive names.
    * Protect "troffrc" from hyphenation.
    * Migrate from macro `LP` to `P`.
    * Adjust dead-tree typography (pagination).

commit f18136cfa818381b6fcb8d336fdb8e192a9a6234
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Mon Aug 22 06:44:26 2022 -0500

    grohtml(1): Organize and clarify.

    Impose more structure on output driver man pages (2/x).

    Fix content nits.
    * Explain why (most) users should only try to approach this output
      device via the groff(1) front end.
    * Document which output device is the default.
    * Parallelize introduction with that of other output drivers.
    * Correctly distinguish output "driver" from output "device" (the former
      is a program; the latter is a parameter in a programming interface).
    * Clarify what sorts of "entities" grohtml writes.
    * Add "Typefaces" subsection, replacing "Usage".  Expand discussion to
      cover the font descriptions actually shipped.
    * Add "Font description files" subsection noting parallelism of glyph
      repertoires in all fonts, an uncommon property.
    * Move discussion of runtime program dependencies into new
      "Dependencies" subsection.
    * Drop trivial and obvious example.
    * Shift discussion from HTML "tags" to "elements".  The details of
      (X)HTML markup are not relevant here.
    * Migrate terminology: "point size" -> "type size".
    * Migrate terminology: "right-justified" -> "right-aligned".
    * Flesh out "Files" section, discussing more than just temporary files.
      Align with other output driver documentation, presenting device and
      font description files, and device-specific macro files.  (The latter
      aren't _opened_ by the driver program, which is why we don't document
      GROFF_TMAC_PATH in the page, but this is most appropriate place to
      discuss them.)

    Fix style nits.
    * Set "Name" section's summary-description terms in italics as needed.
    * Parallelize discussion of (internal) options.  Say what they do first,
      then warn the user off.
    * Shift "only" modifiers to more appropriate syntactical locations.
    * (Environment) Begin sentences with the paragraph tag, to economize and
      align with (material being added to) section "Files".
    * Tighten wording.

    Fix markup nits.
    * Protect "pre-grohtml", "post-grohtml", "grohtml" from hyphenation.
    * Annotate areas where might be able to drop some text outright.  (How
      long ago did Ghostscript lack anti-aliasing support?)


G. Branden Robinson <gbranden>
Group administrator
Tue 11 Jan 2022 10:06:48 PM UTC, comment #1: 

I propose that device man pages should have a section "Typefaces", relatively early in the narrative (before "Options", I should think) since this is a crucial feature to users, that lists all styles/fonts for which groff ships descriptions by default.  (A subsection of "Description" might also be apropos.)

  • grodvi(1) pretty much has this already, as "Usage".


  • grohtml(1) does as well.  It supports only the four basic styles.


  • grolbp(1) has it already under the desired section heading.


  • grolj4(1) has nothing.  There is however the entire man page lj4_font(5), which I propose to merge into this one.  Even that, however, does not comprehensively enumerate the font descriptions available.  So this is the longest pole so far.


  • gropdf(1) has a list under "Usage", albeit mixed with a great deal of other material, including a huge list of device control commands.


  • grops(1)'s structure is parallel to gropdf(1)'s.


  • grotty(1) has this information in a "Typefaces" subsection of "Description".  It's similar to grohtml in that it only covers styles.


  • gxditview(1) has this information in subsection "Default font map" of "Description".


I don't know who still keeps an HP LaserJet jacked to their machine (we don't ever get any bug reports about the driver), but it seems like that's the place to start; it will also enable us to kill one of the 3 groff man pages on my Death List (the others are ditroff(7) and groff_filenames(5)).

G. Branden Robinson <gbranden>
Group administrator
Sat 17 Jul 2021 12:00:31 AM UTC, original submission:  

There isn't a central location that discusses what fonts groff provides by default, and since the fonts provided differ according to each output device, it is hard to find an appropriate central location.

What fonts are available is discussed in grodvi(1), grolbp(1),
gropdf(1), grops(1), and gxditview(1).

grolbp(1) shoudl list the default font family, Times.

grolj4(1) does not list the default fonts available.

While there aren't fonts to be listed on grotty(1), it should probably list the styles available.

Perhaps there should be a reference in groff(1) and groff.texi saying to find information about what fonts are provided by default to look in the man pages for the output processors, and list them.

Mailing List Discussion

T. Kurt Bond <tkurtbond>

 

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

Attach Files:
   
   
Comment:
   

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by gbranden (Posted a comment)
  • -email is unavailable- added by tkurtbond (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 7 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2022-10-28 gbranden StatusIn Progress Fixed
        Open/ClosedOpen Closed
    2022-10-06 gbranden Planned ReleaseNone 1.23.0
    2022-08-22 gbranden StatusNone In Progress
        Assigned toNone gbranden
    2022-01-11 gbranden CategoryNone Driver - others/general
        SummaryImprove documentation of which fonts groff provides by default device man pages should consistently document font repertoire

    Back to the top

    Powered by Savane 3.13-758e.
    Corresponding source code