bugGNU roff - Bugs: bug #61266, [andoc] interacts poorly with page...

 
 

bug #61266: [andoc] interacts poorly with page traps

Submitter:  G. Branden Robinson <gbranden>
Submitted:  Sun 03 Oct 2021 10:47:12 AM UTC
   
 
Category:  Macro - others/general Severity:  3 - Normal
Item Group:  Incorrect behaviour Status:  Fixed
Privacy:  Public Assigned to:  gbranden
Open/Closed:  Closed Planned Release:  1.23.0
* Mandatory Fields

Add a New Comment Rich Markup
   

Sun 03 Oct 2021 01:22:04 PM UTC, comment #1: 


commit a1e6c19176d38823d8dc6c9a619a493ca90bdca4
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Sun Oct 3 23:15:12 2021 +1100

    [andoc,man,mdoc]: Fix Savannah #61266.

    Resolve problems in batch rendering of man pages to PDF arising from
    entanglement of end-of-input traps, page location traps, continuous
    rendering mode, and andoc's reloading of the (m)an and (m)doc packages.

    * tmac/andoc.tmac (reload-doc, reload-man): Remove end-of-input traps
      alongside others.

    * tmac/an.tmac (an-end): Only perform flush and "manual" page footer
      placement if in continuous rendering mode, since this macro is not
      only called by a trap placed only in continuous rendering mode, but
      also by andoc when changing macro packages.  Unconditionally remove
      the `an-header` trap since the next document might be using a
      different macro package.

    * tmac/mdoc/doc-common: In initialization, set flag indicating that
      manual header placement will be required.

      (Dt): Call `doc-setup-header` (which sets up several types of trap)
      unconditionally, and break the page if the vertical drawing position
      is anywhere but at the top.

      (Os): If the package has just been initialized, call `doc-header` to
      force the page header to be written.  (doc-end-macro): Remove
      `doc-header` trap since the next document might be using a different
      macro package.  Break the page.  Set flag indicating that manual
      header placement will be required for the next document.

    * tmac/mdoc/doc-ditroff (doc-setup-header): Only set page location traps
      for the header and footer if not continuously rendering.

    * tmac/mdoc/doc-nroff (doc-setup-header): Stop calling `doc-header` here
      if continuously rendering.  Emit an unconditional break.  Except for
      the location of the footer trap, the `doc-setup-header`
      implementations are now identical.

    Refactoring is needed: some macros and registers have misleading names,
    there is some code duplication in mdoc, and some of the trap management
    problems are solved in slightly different ways in man(7) and mdoc(7),
    perhaps unnecessarily.  We also need some test scripts to protect us
    from regressions.  But this fixes the rendering problems.

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


G. Branden Robinson <gbranden>
Group administrator
Sun 03 Oct 2021 10:47:12 AM UTC, original submission:  

If you try to render all our man pages in one big PDF document, as I do, you will find unhappy results as we transition from man(7) documents to our lone mdoc(7) document and back.

Here's a chunk of script I use to produce such a document.


DIR=$1
MANS=($(find build -name "*.[157]" -and -not -path '*/tests/*'))

mkdir "$DIR"
cp build/doc/groff.pdf "$DIR"

for F in "${MANS[@]}"
do
    echo $F
    if [ -f "$F" ]
    then
        M=$(basename "$F")
        M=${M%.man}
        cp -l "$F" "$DIR"/"$M"
    else
        echo "warning: \"$F\" missing" >&2
    fi
done

./build/test-groff -ww -rCHECKSTYLE=3 -Tpdf -P-e -p -e -t -mandoc -rC1 \
    "$DIR"/*.1 "$DIR"/*.5 "$DIR"/*.7 > "$DIR"/man_pages.pdf


If you examine the resulting document, you will see bad things happen.

1. On page 262, the page footer is drawn right after the end of the man page text, high up the page, and a horizontal line is drawn after it.  These suggest that the `an-end` macro is being called, even though it was intended only for continuous rendering mode (since PDF is paginated, that mode should not be occurring here).
2. On page 262, a second page footer is drawn with is baseline at the exact page bottom, with no margin.
3. On page 263, the header contains stale information from the previous document (groff_man_style(7)), not the current page (groff_mdoc(7)).
4. On page 297, the last page of groff_mdoc(7) and the first page of groff_me(7) are overprinted, with groff_me(7)'s footer again in the midst of the page and a second footer again appears at the  page bottom with no margin.
5. On pages 298-365 (the last), the footer continues to appear in the wrong place, at the page bottom with no margin.

This mess is the result of a horrible web of interaction between several features: continuous rendering support, andoc's macro language detection, and (much older) page location traps and end-of-input traps.

The good news is that I think I've finally got all this sorted after months of being aggrieved by it.

The bad news is that if you think THIS looks bad, try doing the equivalent operation on groff 1.22.4.


...
troff: OLDPDF/eqn2graph.1:213: warning: can't find special character 'u0061_0304'
troff: OLDPDF/eqn2graph.1:215: warning: can't find special character 'u0061_030C'
troff: OLDPDF/groff_font.5:325: warning: can't find special character 'u02DC'
troff: OLDPDF/groff_font.5:608: warning: can't find special character '.j'
troff: OLDPDF/groff_font.5:971: warning: can't find special character 'vA'
warning: page 213: table text block will not fit on one page
troff: OLDPDF/groff_font.5:1051: warning: can't find special character 'bs'
troff: OLDPDF/groff_font.5:1139: warning: can't find special character '-+'
troff: OLDPDF/groff_font.5:1188: warning: can't find special character 'coproduct'
troff: OLDPDF/groff_font.5:1309: warning: can't find special character '+e'
troff: OLDPDF/groff_font.5:1324: warning: can't find special character 'u2661'
troff: OLDPDF/groff_font.5:1326: warning: can't find special character 'u2662'
pic:OLDPDF/groff_mmse.7:158: invalid input character code 133
troff: OLDPDF/groff_font.5:2: fatal error: input stack limit exceeded (probable infinite loop)


G. Branden Robinson <gbranden>
Group administrator

 

(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 (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 3 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2021-10-03 gbranden StatusIn Progress Fixed
        Open/ClosedOpen Closed
        Planned ReleaseNone 1.23.0

    Back to the top

    Powered by Savane 3.13-f8d8.
    Corresponding source code