[bug #61265] macOS sed(1) warns during `make install`

[Dave]

Follow-up Comment #1, bug #61265 (project groff):

Commit feae77a4
 added these
sed commands to doc/doc.am
.  In this file
the sed lines are split exactly as you suggest, so something must be eating
the backslash/newline combo during processing.

___

Reply to this item at:

  

___
  Message sent via Savannah
  https://savannah.gnu.org/

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

[G. Branden Robinson]

Update of bug #61266 (project groff):

  Status: In Progress => Fixed  
 Open/Closed:Open => Closed 
 Planned Release:None => 1.23.0 

___

Follow-up Comment #1:


commit a1e6c19176d38823d8dc6c9a619a493ca90bdca4
Author: G. Branden Robinson 
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 .


___

Reply to this item at:

  

___
  Message sent via Savannah
  https://savannah.gnu.org/

[bug #60927] improve pdfmark documentation, including pdfroff(1)

[Keith Marshall]

Follow-up Comment #1, bug #60927 (project groff):

Hi Kurt,

[comment #0 original submission:]
> Although pdfroff(1) mentions that "transparently handles the
> mechanics of multiple pass groff  processing,  when  applied
> to suitably marked up groff source files, such that tables of
> contents and body text are formatted separately, and are
> subsequently  combined  in  the  correct order, for final
> publication as a single PDF document" it does not indicate
> how to "suitably mark up groff source files."
Suitable mark-up is that described in section 2 of our pdfmark.pdf document,
(which is generated from pdfmark.ms).  Granted, that is rather incomplete; I
am working on it, and have several patches (mostly) ready to commit.

I believe that we could also benefit from the addition of a pdfmark(7), or
maybe better named as groff_pdfmark(7) manpage, and maybe also accompanied by
a groff_pdfhref(7) manpage, to document the appropriate mark-up.  I may
provide something suitable, after I've made pdfmark.pdf more complete.
> The pdfmark.ms file mentions that the .XN macro should be used to
> do this marking up, but the section about the .XN macro is empty
> so how to use it is not documented anywhere.
Uhmm, no.  "XN" (which is provided by spdf.tmac) is only a small element of
the "suitable mark-up"; it serves a very specific purpose, (viz. the
duplication of section heading text, following a "NH" macro call, into the PDF
document outline, and — now optionally — into the TOC diversion, as I've
recently explained on [bug #58946 ticket #58946]), but plays no specific rôle
in controlling the operation of pdfroff(1).

The collation effect of pdfroff(1) is actually controlled by a troff register,
named "PHASE"; if no collation is required, (e.g. as specified by the
"--no-toc-relocation" option), this may remain undefined, or may be defined as
zero; otherwise, it will be defined as 1, in the TOC generation phase, and as
2, in the body-content generation phase.  In each of these phases, the user's
document source is expected to set troff's "pen" state, through "\O" escapes,
as appropriate for each type of content; (completely blank pages, as generated
in the "pen-up" state — and thus, not pertinent in the active phase — will
be discarded during collation).  When formatting with "-mspdf", these phases
are handled transparently, but specific handling may be necessary, for users
of other primary formatting macro packages.

I plan to cover this, in pdfmark.pdf, but I agree that it should also be
documented in the pdfroff(1) manpage.

___

Reply to this item at:

  

___
  Message sent via Savannah
  https://savannah.gnu.org/

[bug #58946] [ms] adapt to use the facilities of pdfmark

[G. Branden Robinson]

Follow-up Comment #11, bug #58946 (project groff):

Hi, Keith!

Yes, I like your proposal for two reasons.

1. As I was porting my updates from groff_ms(7) to doc/ms.ms (whence the
language about the "Groff and Friends HOWTO" originates), I found myself
wincing pretty hard.  I thought to myself, "why don't we just offer the user a
pre-rolled solution to this straightforward problem"?  I also learned things
about the .XA macro that I never knew because no one had really documented
then.  (They're in groff_ms(7) now.)

[I haven't pushed my changes to doc/ms.ms yet--I got distracted because I
finally felt equal to the task of stomping bug #61266.]

2. Dean Allen Provins's "Groff and Friends HOWTO" doesn't seem like a bad
document but it has not been updated in literally 20 years.  Even slow-moving
groff has developed in that time, mostly thanks to Werner, Deri, and you. 
Moreover, the document is broad-reaching and while I haven't perused it, I'm
pretty nervous about the diverse and deep potential for outdated advice.

> I'm wondering if there may be some justification for incorporation of
simplified versions of each of these, and maybe also a minimal default
implementation of "XH-UPDATE-TOC", within s.tmac?

> What do you think?

I think "yes"!  Please go for it.  It drives me crazy that we're advising
people to violate the DRY principle with respect to section headings and,
worse, to count tabs.

Simplified is good, and if you have hooks in these simplified versions such
that additional features and coolness and PDF-enhancements spring to life when
-mspdf is specified, that's great!

The only thing I would ask--and it may not be relevant as I have little
familiarity with pdfmark and spdf--is to not wall up _external_ hyperlink
support behind the PDF device.  As you probably saw on the groff development
list, the planets are coming into alignment for a generalized, cross-device
hyperlinking facility.

I don't, however, see at this point any way to enable within-document anchors
and links for terminal devices.  I'm sure it's not impossible, given things
like addressable scrollback buffers in terminal emulators and less(1)'s
existing ability to seek its input stream, but at present I know of no way to
tell a terminal how to place an anchor, so there's nothing to navigate to.  So
that is a problem for another day, and for people like Egmont Koblinger who
have many tentacles to spare for terminal emulation and pager development
communities.

I apologize if that digresses from anything you have in mind.

Regards,
Branden

___

Reply to this item at:

  

___
  Message sent via Savannah
  https://savannah.gnu.org/

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

[G. Branden Robinson]

URL:
  

 Summary: [andoc] interacts poorly with page traps
 Project: GNU troff
Submitted by: gbranden
Submitted on: Sun 03 Oct 2021 10:47:12 AM UTC
Category: Macro - others
Severity: 3 - Normal
  Item Group: Incorrect behaviour
  Status: In Progress
 Privacy: Public
 Assigned to: gbranden
 Open/Closed: Open
 Discussion Lock: Any
 Planned Release: None

___

Details:

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)






___

Reply to this item at:

  

___
  Message sent via Savannah
  https://savannah.gnu.org/

[bug #58946] [ms] adapt to use the facilities of pdfmark

[Keith Marshall]

Follow-up Comment #10, bug #58946 (project groff):

I have now reworked spdf.tmac, to incorporate only those macros identified in
comment #9 as "necessary"; I _have_ included a completely reworked
implementation of "XN", (which also serves as a new "XH" macro, courtesy of
groff's .als mechanism).

As now implemented, the "XH" and "XN" macros conform to the following calling
syntax:

.SH
.XH [-option ...]   ...

.NH 
.XN [-option ...]  ...

In both cases, the permitted options are:

-NPlace a pdfhref destination mark, with the given name,
at the location of this heading.

-S  Sanitize  (by removal of "\F" escapes)
for use in the PDF document outline.

-X  Create a pdfhref cross-reference dictionary entry for
this heading; use the destination name specified by
-N , if given, or the first word taken from
 if not.

Both of these new macro implementations ("XH" and "XN") reproduce their
 argument(s) as running text, in the appropriate heading
font/size, and as PDF document outline entries, at the specified
, and sanitized as required.  Neither creates a TOC entry, by
default; however, each invokes a pair of callback hooks:

XH-INIT
XN-INIT
   Called on entry to XH, and XN respectively; by default, each is
   a no-op, but either, or both, may be redefined by the user, to
   perform any respective initialization, for use by:

XH-UPDATE-TOC  [] 
   Called by both XH and XN, (the  argument is
   omitted, when called by XH, and always present, when called by
   XN); once again, this is a no-op by default, but may be redefined
   by the user, to generate TOC entries.

As I had previously observed in comment #4, neither this implementation of
"XN", nor its new "XH" sibling, is an appropriate candidate for inclusion in
s.tmac; however, given this statement in the groff online manual
 (not
reproduced in groff_ms(7)):

The Groff and Friends HOWTO includes a sed script that automatically inserts
XS and XE macro entries after each heading in a document.

Altering the NH macro to automatically build the table of contents is perhaps
initially more difficult, but would save a great deal of time in the long run
if you use ms regularly.

and given that "XH" and "XN" can facilitate linking of TOC entries to section
headings, I'm wondering if there may be some justification for incorporation
of simplified versions of each of these, and maybe also a minimal default
implementation of "XH-UPDATE-TOC", within s.tmac?

What do you think?

___

Reply to this item at:

  

___
  Message sent via Savannah
  https://savannah.gnu.org/