[src/trunk]: src/distrib/notes Add a table of contents (TOC) to the release n...

[jhawk <jhawk%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/46082e9c4921
branches:  trunk
changeset: 518180:46082e9c4921
user:      jhawk <jhawk%NetBSD.org@localhost>
date:      Mon Nov 26 00:19:56 2001 +0000

description:
Add a table of contents (TOC) to the release notes.
This makes it _much_ more user-friendly, as it allows users
  to skip to the parts they want easily.
At present, the TOCs are generated files, and can be regenerated
  with "make tocs" (probably has to be run twice to account for
  the size of the table itself).
TOCs are named INSTALL.{PostScript,ASCII,HTML,more}.toc instead of
  INSTALL.{ps,txt,html,more}.toc because that's what \*[format]
  expands to.

diffstat:

 distrib/notes/Makefile.inc  |  27 +++++++++++++++++++++++++--
 distrib/notes/common/macros |  42 ++++++++++++++++++++++++++++++++++++++++--
 distrib/notes/common/main   |   4 +++-
 3 files changed, 68 insertions(+), 5 deletions(-)

diffs (135 lines):

diff -r 67295abd2705 -r 46082e9c4921 distrib/notes/Makefile.inc
--- a/distrib/notes/Makefile.inc        Mon Nov 26 00:14:19 2001 +0000
+++ b/distrib/notes/Makefile.inc        Mon Nov 26 00:19:56 2001 +0000
@@ -1,4 +1,4 @@
-#      $NetBSD: Makefile.inc,v 1.18 2001/01/14 21:45:01 mycroft Exp $
+#      $NetBSD: Makefile.inc,v 1.19 2001/11/26 00:19:56 jhawk Exp $
 #
 
 # Ross Harvey <ross%netbsd.org@localhost>
@@ -12,6 +12,8 @@
 MAIN=  ${.CURDIR}/../common/main ${.CURDIR}/../common/macros ${EXTRA}
 TARG=  INSTALL
 TARGS= ${TARG}.ps ${TARG}.txt ${TARG}.html ${TARG}.more
+TOCS=  ${TARG}.PostScript.toc ${TARG}.ASCII.toc ${TARG}.HTML.toc \
+       ${TARG}.more.toc
 SRCS=  ${MAIN} whatis contents hardware xfer prep install\
        upgrade donations legal.common legal postinstall ../Makefile.inc\
        ${MERGED_SRCS}
@@ -55,6 +57,27 @@
 ${TARG}.more: ${SRCS}
        groff ${ARGS_MORE} -mdoc      ${MAIN} > $@
 
+tocs: ${TOCS}
+
+TOCPROC=          2>&1 >/dev/null |\
+           sed -n '/^\.Ti/{s/ \([A-Za-z]\)/ "\1/; s/ *$$/"/; p; }'
+
+${TARG}.PostScript.toc: .PHONY
+       groff -dTOC=1 ${ARGS_PS} -mdoc ${MAIN} ${TOCPROC} > $@.tmp
+       mv -f $@.tmp $@
+
+${TARG}.ASCII.toc: .PHONY
+       groff -dTOC=1 ${ARGS_TXT} -mdoc ${MAIN} ${TOCPROC} > $@.tmp
+       mv -f $@.tmp $@
+
+${TARG}.HTML.toc: .PHONY
+       groff -dTOC=1 ${ARGS_HTML} -mdoc ${MAIN} ${TOCPROC} > $@.tmp
+       mv -f $@.tmp $@
+
+${TARG}.more.toc: .PHONY
+       groff -dTOC=1 ${ARGS_MORE} -mdoc ${MAIN} ${TOCPROC} > $@.tmp
+       mv -f $@.tmp $@
+
 echosrcs! ${SRCS}
        @echo ${.ALLSRC}
 
@@ -73,6 +96,6 @@
 .PATH: ${.CURDIR}/../common
 
 cleannotes:
-       rm -f [Ee]rrs mklog core *.core ${TARGS}
+       rm -f [Ee]rrs mklog core *.core ${TARGS} ${TOCS}
 
 clean cleandir distclean: cleannotes
diff -r 67295abd2705 -r 46082e9c4921 distrib/notes/common/macros
--- a/distrib/notes/common/macros       Mon Nov 26 00:14:19 2001 +0000
+++ b/distrib/notes/common/macros       Mon Nov 26 00:19:56 2001 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: macros,v 1.11 2001/07/24 17:46:07 nra Exp $
+.\"    $NetBSD: macros,v 1.12 2001/11/26 00:19:57 jhawk Exp $
 .\"
 .\" Copyright (c) 1999, 2000 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -176,7 +176,7 @@
 .\" support for more than two pages, nor for right-margins.
 .\" Usage:
 .\"   .Bc [ncol]
-.\" Dependances:
+.\" Dependancies:
 .\"  macro CF   page trap macro for bottom of column
 .\"  macro CZ   code duplication; handling of diversion interpolation.
 .\"  macro CC   diversion trap macro for subdividing into pages.
@@ -304,6 +304,44 @@
 .als Ec Ed
 .\}
 .
+.\" Macros to support Table of Contents
+.\" TOC is set (from the command line) if we're generating the TOC file;
+.\" the TOC file is read from groff's stderr.
+.\" Usage:
+.\"   .Sh                      section header
+.\"   .Ss                      subsection header
+.\"   .Ss2                     sub2section header
+.\" XXX: Do we want .Te [explicit toc entry, not based on other markup]?
+.\"   .Tc                      import the TOC
+.\"   .Ti depth page "item"    (internal) output an entry
+.if dTOC \{
+.rn Sh Sh-toc
+.de Sh
+.Sh-toc \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
+\.tm .Ti 0 \\n% \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
+..
+.rn Ss Ss-toc
+.de Ss
+.Ss-toc \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
+\.tm .Ti 1 \\n% \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
+..
+.rn Ss2 Ss2-toc
+.de Ss2
+.Ss2-toc \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
+\.tm .Ti 2 \\n% \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
+..
+.\}
+.de Ti
+\h'3n*\\$1u' \\$3\a\\$2
+..
+.de Tc
+.Bd -literal
+.ta (\n(.lu)R
+\.so INSTALL.\*[format].toc
+.Ed
+..
+.
+.
 .\"    --------------------  MISC  --------------------
 .
 .\" set the unused target number registers to 0, so that we can turn on all
diff -r 67295abd2705 -r 46082e9c4921 distrib/notes/common/main
--- a/distrib/notes/common/main Mon Nov 26 00:14:19 2001 +0000
+++ b/distrib/notes/common/main Mon Nov 26 00:19:56 2001 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: main,v 1.144 2001/11/23 16:30:54 bjh21 Exp $
+.\"    $NetBSD: main,v 1.145 2001/11/26 00:19:57 jhawk Exp $
 .\"
 .\" Copyright (c) 1999-2001 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -57,6 +57,8 @@
 .Nm INSTALL
 .Nd Installation procedure for
 .Nx*M .
+.Sh CONTENTS
+.Tc
 .Sh DESCRIPTION
 .
 .Ss About this Document