[Groff-commit] groff/contrib/pdfmark ChangeLog pdfmark.ms pdfm...

[Werner LEMBERG]

CVSROOT:        /cvsroot/groff
Module name:    groff
Branch:         
Changes by:     Werner LEMBERG <address@hidden> 05/04/25 07:16:20

Modified files:
        contrib/pdfmark: ChangeLog pdfmark.ms pdfmark.tmac 

Log message:
        Add support for folded outlines in PDF documents.
        
        * pdfmark.tmac (PDFOUTLINE.FOLDLEVEL): New register.
        (pdf:bm.emit): Use it.
        
        * pdfmark.ms: Document it.

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/groff/groff/contrib/pdfmark/ChangeLog.diff?tr1=1.7&tr2=1.8&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/groff/groff/contrib/pdfmark/pdfmark.ms.diff?tr1=1.1&tr2=1.2&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/groff/groff/contrib/pdfmark/pdfmark.tmac.diff?tr1=1.2&tr2=1.3&r1=text&r2=text

Patches:
Index: groff/contrib/pdfmark/ChangeLog
diff -u groff/contrib/pdfmark/ChangeLog:1.7 groff/contrib/pdfmark/ChangeLog:1.8
--- groff/contrib/pdfmark/ChangeLog:1.7 Fri Mar 25 01:46:25 2005
+++ groff/contrib/pdfmark/ChangeLog     Mon Apr 25 07:16:20 2005
@@ -1,3 +1,12 @@
+2005-04-24  Keith Marshall  <address@hidden>
+
+       Add support for folded outlines in PDF documents.
+
+       * pdfmark.tmac (PDFOUTLINE.FOLDLEVEL): New register.
+       (pdf:bm.emit): Use it.
+
+       * pdfmark.ms: Document it.
+
 2005-03-25  Werner LEMBERG  <address@hidden>
 
        * Makefile.in: Removed.
@@ -10,7 +19,7 @@
 2005-03-22  Keith Marshall  <address@hidden>
 
        * pdfroff.sh: Eliminate invalid program reference to $AWK, when
-       invoked with `--no-reference-dictionary-option'.
+       invoked with `--no-reference-dictionary' option.
 
 2005-03-02  Keith Marshall  <address@hidden>
 
Index: groff/contrib/pdfmark/pdfmark.ms
diff -u groff/contrib/pdfmark/pdfmark.ms:1.1 
groff/contrib/pdfmark/pdfmark.ms:1.2
--- groff/contrib/pdfmark/pdfmark.ms:1.1        Wed Dec  8 08:31:17 2004
+++ groff/contrib/pdfmark/pdfmark.ms    Mon Apr 25 07:16:20 2005
@@ -10,6 +10,11 @@
 .\"
 .pdfview /PageMode /UseOutlines
 .\"
+.\" Initialise the outline view to show only three heading levels,
+.\" with additional subordinate level headings folded.
+.\"
+.nr PDFOUTLINE.FOLDLEVEL 3
+.\"
 .\" Add document identification meta-data
 .\"
 .pdfinfo /Title     Portable Document Format Publishing with GNU Troff
@@ -844,6 +849,79 @@
 .CW pdfhref
 macro.
 .NH 3
+.XN -N outline-folding -- Folding the Outline to Conceal Less Significant 
Headings
+.LP
+When a document incorporates many subheadings,
+at deeply nested levels,
+it may be desirable to \(lqfold\(rq the outline
+such that only the major heading levels are initially visible,
+yet making the inferior subheadings accessible,
+by allowing the reader to expand the view of any heading branch on demand.
+.LP
+The
+.CW pdfmark
+macros support this capability,
+through the setting of the
+.CW PDFOUTLINE.FOLDLEVEL
+register.
+This register should be set to the number of heading levels
+which it is desired to show in expanded form, in the
+.EM initial
+document outline display;
+all subheadings at deeper levels will still be added to the outline,
+but will not become visible until the outline branch containing them is 
expanded.
+'ne 5
+For example, the setting used in this document:
+.QS
+.LD
+.fam C
+\&.\e" Initialise the outline view to show only three heading levels,
+\&.\e" with additional subordinate level headings folded.
+\&.\e"
+\&.nr PDFOUTLINE.FOLDLEVEL 3
+.DE
+.QE
+.LP
+results in only the first three levels of headings being displayed
+in the document outline,
+.EM until
+the reader chooses to expand the view,
+and so reveal the lower level headings in any outline branch.
+.LP
+The initial default setting of
+.CW PDFOUTLINE.FOLDLEVEL ,
+if the document author does not choose to change it,
+is 10,000.
+This is orders of magnitude greater than the maximum heading level
+which is likely to be used in any document;
+thus the default behaviour will be to show document outlines fully expanded,
+to display all headings defined,
+at all levels within each document.
+.LP
+The setting of
+.CW PDFOUTLINE.FOLDLEVEL
+may be changed at any time;
+however, the effect of each such change may be difficult to predict,
+since it is applied not only to outline entries which are defined
+.EM after
+the setting is changed,
+but also to any entries which remain in the outline cache,
+.EM at
+this time.
+Therefore, it is recommended that
+.CW PDFOUTLINE.FOLDLEVEL
+should be set
+.EM once ,
+at the start of each document;
+if it
+.EM is
+deemed necessary to change it at any other time,
+the outline cache should be flushed,
+.XR pdfsync ), (
+.EM immediately
+before the change,
+which should immediately preceed a level one heading.
+.NH 3
 .XN -N multipart-outline -- Outlines for Multipart Documents
 .LP
 When a document outline is created, using the
Index: groff/contrib/pdfmark/pdfmark.tmac
diff -u groff/contrib/pdfmark/pdfmark.tmac:1.2 
groff/contrib/pdfmark/pdfmark.tmac:1.3
--- groff/contrib/pdfmark/pdfmark.tmac:1.2      Mon Feb 28 13:56:45 2005
+++ groff/contrib/pdfmark/pdfmark.tmac  Mon Apr 25 07:16:20 2005
@@ -272,6 +272,15 @@
 .\"
 .ds PDFBOOKMARK.VIEW /FitH \\n[PDFPAGE.Y] u
 .\"
+.\" "PDFOUTLINE.FOLDLEVEL" controls how the document outline will be
+.\" displayed.  It is a number, defining the maximum heading level
+.\" which will be visible, without outline expansion by the user, in
+.\" the initial view of the document outline.  Assuming that no sane
+.\" document will ever extend to 10,000 levels of nested headings,
+.\" this initial default value causes outlines to be fully expanded.
+.\"
+.nr PDFOUTLINE.FOLDLEVEL 10000
+.\"
 .\" The actual job of creating an outline reference
 .\" is performed by the "pdfbookmark" macro.
 .\"
@@ -390,7 +399,12 @@
 .nr pdf:bm.ic +1
 .nr pdf:bm.lc +1
 .pdf:pop nr pdf:bm.rc pdf:bm.c\\n[pdf:bm.lc]
-.if \\n[pdf:bm.rc] .as pdf:bm\\n[pdf:bm.ic] " /Count \\n[pdf:bm.rc]
+.if \\n[pdf:bm.rc] \{\
+.   ds pdf:bm.fold
+.   if \\n[pdf:bm.lc]>\\n[PDFOUTLINE.FOLDLEVEL] .ds pdf:bm.fold -
+.   as pdf:bm\\n[pdf:bm.ic] " /Count \\*[pdf:bm.fold]\\n[pdf:bm.rc]
+.   rm pdf:bm.fold
+.   \}
 .pdfmark \\*[pdf:bm\\n[pdf:bm.ic]] /OUT
 .rm pdf:bm\\n[pdf:bm.ic]
 .\"