diff options
Diffstat (limited to 'contrib/groff/contrib/mom/momdoc/cover.html')
-rw-r--r-- | contrib/groff/contrib/mom/momdoc/cover.html | 512 |
1 files changed, 0 insertions, 512 deletions
diff --git a/contrib/groff/contrib/mom/momdoc/cover.html b/contrib/groff/contrib/mom/momdoc/cover.html deleted file mode 100644 index 2566547cb511..000000000000 --- a/contrib/groff/contrib/mom/momdoc/cover.html +++ /dev/null @@ -1,512 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<html> -<head> -<meta http-equiv="content-type" content="text/html;charset=iso-8859-1"> -<title>Mom -- Document processing, creating a cover page</title> -</head> -<body bgcolor="#dfdfdf"> - -<!====================================================================> - -<a href="refer.html#TOP">Next</a> -<a href="rectoverso.html#TOP">Prev</a> -<a href="toc.html">Back to Table of Contents</a> -<p> - -<a name="TOP"> -<h1 align="center"><u>CREATING A COVER PAGE</u></h1> -</a> - -<ul> - <li><a href="#COVER_INTRO">Introduction to cover pages</a> - <ul> - <li><a href="#PLEASE">Important note -- please read</a> - <li><a href="#DESC">Description of what mom does on cover pages</a> - <li><a href="#PAGINATION">A note on headers/footers and pagination</a> - <li><a href="#DESIGN">What to do if you want to design your - own cover pages</a> - </ul> - <li><a href="#COVER">The cover and document cover macros</a> - <ul> - <li><a href="#COVER">COVER/DOC_COVER</a> - <ul> - <li><a href="#REQUIRED">The required argument</a> - <li><a href="#CHAPTER">How the CHAPTER argument and friends work</a> - <li><a href="#OPTIONAL">The optional arguments</a> - <li><a href="#DOCTYPE">What the DOCTYPE argument means</a> - </ul> - </ul> - <li><a href="#ON_OFF">Enabling/disabling automatic generation of cover pages</a> - <li><a href="#COVER_CONTROL">Control macros--changing the - defaults for covers and document covers</a> -</ul> - -<a name="COVER_INTRO"><h2><u>Introduction to cover pages</u></h2></a> -<p> -As of version 1.19 of <strong>mom</strong>, you can now have cover -pages generated automatically. -<p> -Though identical in treatment, <strong>mom</strong> provides two -kinds of cover pages: section cover pages (which I shall refer to -simply as "cover pages") and document cover pages -("doc covers"). -<p> -A document cover page -(<a href="#DOC_COVER">doc cover</a>) -is what you'd most likely use at the start of a <a -href="rectoverso.html#COLLATE_INTRO">collated</a> document, where -you might want the name of the complete document, the author(s) and -the copyright line to appear. Another place you might use a doc -cover is for a novel, where you want the title of the novel, not -the chapter title or chapter number, as the first cover page. -<p> -A section -<a href="#COVER">cover</a> -page is what you'd use for cover pages that separate sections of a -collated document. A section cover page (but not a doc cover page) -in a collated document could, for example, simply read "PART -I". -<p> -In non-collated documents (say, an essay) you can use either a -section cover or a doc cover to generate a cover sheet. -<p> -In addition, nothing prevents you from generating both a doc cover -page and a section cover page for every document in a collated -document. Or you can selectively disable the automatic generation -of either doc covers or section covers in a collated document, -on-the-fly. -<p> -<a name="PLEASE"><strong>Important note:</strong></a> -automatic generation of cover or doc cover pages after the first -one(s) only takes place if you are working with collated documents. -<strong>Mom</strong> provides no mechanism for saying "print -a section cover here even though I'm still working on the same -(non-collated) document." - -<a name="DESC"><h3><u>Description of what mom does on cover pages</u></h3></a> - -By default, <strong>mom</strong> typesets cover (and doc cover) -pages identically to -<a href="definitions.html#TERMS_DOCHEADER">docheaders</a> -(see -<a href="docprocessing.html#DOCHEADER_CONTROL">How to change the look of docheaders</a> -for a description of what a docheader looks like). The only -differences are -<br> -<ul> - <li>the position on the page where the information is output - <li>the (optional) addition of copyright and miscellaneous - information - <li>there's no running text underneath -</ul> - -<p> -You tell <strong>mom</strong> what you want to appear on the cover -pages through the arguments you pass to -<a href="#COVER">COVER</a> -and/or -<a href="#COVER">DOC_COVER</a>. -Provided you have already given <strong>mom</strong> the -appropriate references macro (e.g. -<a href="docprocessing.html#TITLE">TITLE</a> -or -<a href="docprocessing.html#AUTHOR">AUTHOR</a>), -she will output cover (and doc cover) pages identically to how she -would output docheaders containing the same information. -<p> -By default, <strong>mom</strong> starts cover (and doc cover) pages -one-third of the way down the page. This can be changed through -the use of the control macros -<a href="#COVER_CONTROL_INDEX">COVER_ADVANCE/DOC_COVER_ADVANCE</a>. -<p> -If you request copyright information (and have already given -<strong>mom</strong> the reference macro, -<a href="docprocessing.html#COPYRIGHT">COPYRIGHT</a>), -she sets it, by default, in a smaller -<a href="definitions.html#TERMS_PS">point size</a> -in the bottom right hand corner of the cover (or doc cover) page. -The default point size and the position can be controlled -with -<a href="#COVER_CONTROL_INDEX">COVER_COPYRIGHT_SIZE/DOC_COVER_COPYRIGHT_SIZE</a> -and -<a href="#COVER_CONTROL_INDEX">COVER_COPYRIGHT_QUAD/DOC_COVER_COPYRIGHT_QUAD</a>. -<p> -Similarly, if you request miscellaneous information (and have already given -<strong>mom</strong> the reference macro, -<a href="docprocessing.html#MISC">MISC</a>), -she sets it, by default, in a smaller point size in the bottom left -hand corner of the cover (or doc cover) page. The default point -size is dependent on -<strong>COVER_COPYRIGHT_SIZE/DOC_COVER_COPYRIGHT_SIZE</strong>, -but the position can be controlled with -<a href="#COVER_CONTROL_INDEX">COVER_MISC_QUAD/DOC_COVER_MISC_QUAD</a>. - -<a name="PAGINATION"></a> -<p> -<strong>NOTE: mom</strong> does not set any -<a href="definitions.html#TERMS_HEADER">headers</a> -or -<a href="definitions.html#TERMS_FOOTER">footers</a> -on cover pages. Neither does she set any page numbers. From the -point of pagination, cover (and doc cover) pages are considered -"null" pages; if you wish them to be included in the -pagination scheme (even though no page numbers appear), you must -set the page number of each first page following a -<a href="rectoverso.html#COLLATE">COLLATE</a> -manually with -<a href="headfootpage.html#PAGENUMBER">PAGENUMBER</a>. - -<a name="DESIGN"></a> -<p> -Finally, if you want to design your own cover page(s), you can -always typeset them (using the -<a href="typesetting.html#MACROS_TYPESETTING">typesetting macros</a>), -invoke -<a href="typesetting.html#NEWPAGE">NEWPAGE</a>, -set up your document <em>in full</em> (see -<a href="docprocessing.html#DOCPROCESSING_TUT">Tutorial -- Setting up a mom document</a>), -and lastly invoke -<a href="docprocessing.html#START">START</a>. -The cover page (and any typesetting commands on it) will have no -effect on <strong>mom</strong>'s processing of the document itself, -the first page of which, moreover, will be numbered "1" -unless you instruct her otherwise with -<a href="headfootpage.html#PAGENUMBER">PAGENUMBER</a>. -<p> - -<!---COVER---> - -<hr width="66%" align="left"> -<p> -<a name="COVER"></a> - Macro: <strong>COVER</strong> - <br> - Macro: <strong>DOC_COVER</strong> - <br> - Required argument: <nobr>TITLE | DOCTITLE | COVERTITLE | CHAPTER | CHAPTER_TITLE | CHAPTER+TITLE</nobr> - <br> - Optional arguments: <nobr>[ SUBTITLE AUTHOR DOCTYPE COPYRIGHT MISC ]</nobr> - <p> - <em>*Note: these macros should be placed in the - "style-sheet" section of your document setup (see the - <a href="docprocessing.html#DOCPROCESSING_TUT">Tutorial -- Setting up a mom document</a>), - i.e. after PRINTSTYLE (and/or DOCTYPE and/or COPYSTYLE), but - before START.</em> - -</a> -<p> -<strong>COVER</strong> and <strong>DOC_COVER</strong> behave -identically. The reason <strong>mom</strong> provides two macros -for automatic cover page generation is so that you can have two -different kinds of covers with different information on each. -<p> -Imagine, for a moment, you've written a document comprised of three -sections. When you -<a href="rectoverso.html#COLLATE">COLLATE</a> -the document for output, you could use <strong>DOC_COVER</strong> -to generate a cover page that contained the name of the entire -document, your (the author's) name, and perhaps the copyright date. -Subsequently, you could use <strong>COVER</strong>, after each -<strong>COLLATE</strong> but before each -<a href="docprocessing.html#START">START</a>, -to generate a cover page (or cover "sheet", if you prefer) -containing just the name of the section. -<br> - -<a name="REQUIRED"><h3><u>The required argument</u></h3></a> - -Both <strong>COVER</strong> and <strong>DOC_COVER</strong>, whenever -invoked, require a first argument, as listed above. This first argument -will become the first bit of information <strong>mom</strong> -prints on the cover (or doc cover) page (i.e. it will be the -"title"). -<p> -In order for the information to appear, you must, of course, first -have given <strong>mom</strong> the appropriate -<a href="docprocessing.html#REFERENCE_MACROS">reference macro</a>. -A list of arguments with their equivalent reference macros follows. -<br> - -<dl> -<dt>TITLE -<dd>-means the argument you gave to -<a href="docprocessing.html#TITLE">TITLE</a> -<dt>DOCTITLE -<dd>-means the argument you gave to -<a href="docprocessing.html#DOCTITLE">DOCTITLE</a> -<dt>COVERTITLE -<dd>-means the argument you gave to -<a href="docprocessing.html#COVERTITLE">COVERTITLE</a> -or -<a href="docprocessing.html#DOC_COVERTITLE">DOC_COVERTITLE</a> -<dt>CHAPTER, CHAPTER_TITLE, CHAPTER+TITLE -<dd>-see below (How the CHAPTER argument and friends work) -</dl> -<br> - -<a name="CHAPTER"><h3><u>How the CHAPTER argument and friends work</u></h3></a> - -<kbd>CHAPTER</kbd>, by itself, will print the <a -href="docprocessing.html#CHAPTER_STRING">CHAPTER_STRING</a> as well -as the chapter number that you gave to -<a href="docprocessing.html#CHAPTER">CHAPTER</a>. -For example, assuming a vanilla setup for your chapter -<p> -<pre> - \# Reference macros - .CHAPTER 1 - .CHAPTER_TITLE "The Bonny Blue Yonder" - <other stuff> - .COVER CHAPTER \" (or .DOC_COVER CHAPTER) - .START -</pre> - -will simply print -<p> -<pre> - Chapter 1 -</pre> - -<kbd>CHAPTER_TITLE</kbd> will print the chapter title you -gave to -<a href="docprocessing.html#CHAPTER_TITLE">CHAPTER_TITLE</a>. -For example, assuming a vanilla setup for your chapter -<p> -<pre> - \# Reference macros - .CHAPTER 1 - .CHAPTER_TITLE "The Bonny Blue Yonder" - <other stuff> - .COVER CHAPTER_TITLE \" (or .DOC_COVER CHAPTER_TITLE) - .START -</pre> - -will simply print -<p> -<pre> - The Bonny Blue Yonder -</pre> - -<p> -<kbd>CHAPTER+TITLE</kbd> will print <strong>both</strong> the -chapter string + number AND the chapter title. For example, -assuming a vanilla setup for your chapter -<p> -<pre> - \# Reference macros - .CHAPTER 1 - .CHAPTER_TITLE "The Bonny Blue Yonder" - <other stuff> - .COVER CHAPTER+TITLE \" (or .DOC_COVER CHAPTER+TITLE) - .START -</pre> - -will print -<p> -<pre> - Chapter 1 - The Bonny Blue Yonder -</pre> - -<a name="OPTIONAL"><h3><u>The optional arguments</u></h3></a> - -The remainder of the arguments to <strong>COVER</strong> and -<strong>DOC_COVER</strong> are optional. They refer specifically -to the information you gave the -<a href="docprocessing.html#REFERENCE_MACROS">reference macros</a> -bearing the same name as the arguments. -<p> -You may enter as many or as few as you would like to see on your -cover (or doc cover) page. The only hitch is--PAY ATTENTION, -CLASS!--they must be entered in the order given above. For -example, if you want <kbd>TITLE</kbd>, <kbd>AUTHOR</kbd>, -<kbd>COPYRIGHT</kbd> and <kbd>MISC</kbd> -<p> -<pre> - .COVER TITLE AUTHOR COPYRIGHT MISC -</pre> - -is correct, while -<p> -<pre> - .COVER TITLE AUTHOR MISC COPYRIGHT -</pre> - -is not. -<br> - -<a name="DOCTYPE"><h3><u>What the DOCTYPE argument means</u></h3></a> - -When you pass <strong>COVER</strong> or <strong>DOC_COVER</strong> -the argument, <kbd>DOCTYPE</kbd>, it refers to the argument you -gave to -<a href="docprocessing.html#DOCTYPE">DOCTYPE</a> <kbd>NAMED</kbd>. -For example, if, in your -<a href="docprocessing.html#DOCSTYLE_MACROS">docstyle macros</a> -you gave a -<p> -<pre> - .DOCTYPE NAMED "Abstract" -</pre> - -the argument, <kbd>DOCTYPE</kbd>, in the <strong>COVER</strong> or -<strong>DOC_COVER</strong> macros, would mean that you wanted the -word, Abstract, to appear on the cover (or doc cover), just as it -would in the -<a href="docprocessing.html#DOCHEADER">docheader</a>. -<br> - -<!---ENABLING/DISABLING---> - -<hr width="66%" align="left"> -<p> -<a name="ON_OFF"></a> - <nobr>Macro: <strong>COVERS</strong> <toggle></nobr> - <br> - <nobr>Macro: <strong>DOC_COVERS</strong> <toggle></nobr> -</a> -<p> -By default, if you give <strong>mom</strong> a -<a href="#COVER">COVER</a> -or -<a href="#DOC_COVER">DOC_COVER</a> -macro, she will print it. In a document that contains sections, -articles or chapters formerly treated as "one-off's" but -now being -<a href="rectoverso.html#COLLATE_INTRO">collated</a>, -such behaviour may not be desirable. -<p> -<strong>Mom</strong> lets you selectively enable or disable the -generation of covers and/or doc covers with the toggle macros -<strong>COVERS</strong> and <strong>DOC_COVERS</strong>. Because -they're toggle macros, simply invoking them by themselves enables -automatic cover (or doc cover) generation, while invoking them -with any argument at all (<strong>OFF, QUIT, X</strong>, etc) -disables cover (or doc cover) generation. -<p> -<strong>NOTE:</strong> You must place these macros prior to any -instance of -<a href="docprocessing.html#START">START</a>. Since they're -"on" by default, there's no need to use them if you want -covers. However, if you don't, especially in the kind of scenario -described above, the best place to put them (most likely with an -<strong>OFF, NO, X</strong>, etc. argument), is immediately after the -first invocation of <strong>START</strong>. By doing so, you ensure -they precede all subsequent instances of <strong>START</strong>. -<p> - -<hr> -<p> -<a name="COVER_CONTROL"><h3><u>Control macros--changing the defaults for covers and document covers</u></h3></a> -The default typographic appearance of the items on a cover (or doc -cover) page is identical to that of the items in a -<a href="definitions.html#TERMS_DOCHEADER">docheader</a>. -(See -<a href="docprocessing.html#DOCHEADER_CONTROL">How to change the look of docheaders</a> -for a description of the defaults.) -<p> -<a href="docprocessing.html#COPYRIGHT">COPYRIGHT</a> -and -<a href="docprocessing.html#MISC">MISC</a>, -which do not appear in docheaders, have the following default -characteristics: -<br> -<ol> - <li>The copyright line is set in the bottom right hand corner - of the page, 2 - <a href="definitions.html#TERMS_PS">point sizes</a> - smaller than the size of - <a href="definitions.html#TERMS_RUNNING">running text</a> - <li>The "misc" line is set in the bottom left hand - corner of the page, in the same family, font and point size - as the copyright line. -</ol> -<p> -With the exception of the copyright and "misc" lines, the -defaults for the entirety of cover (and doc cover) pages, and all -the elements thereon, can be changed with control macros whose -behaviour and arguments are identical to -<a href="docprocessing.html#DOCHEADER_CONTROL_INDEX">the control macros used for docheaders</a>. -The only difference is the name by which you invoke the control -macro(s). -<p> -The complete list of cover (and doc cover) page control macros -follows; please refer to the -<a href="docprocessing.html#DOCHEADER_CONTROL_INDEX">docheader control macros index</a> -in order to understand how to use them. -<p> -<a name="COVER_CONTROL_INDEX"><h3><u>Index of cover and doc cover control macros</u></h3></a> -<pre> -<a name="COVER_ADVANCE">.COVER_ADVANCE .DOC_COVER_ADVANCE</a> -+ -<a name="COVER_FAMILY">.COVER_FAMILY .DOC_COVER_FAMILY</a> | like DOCHEADER_ -<a name="COVER_LEAD">.COVER_LEAD .DOC_COVER_LEAD</a> -+ - -.COVER_TITLE_FAMILY .DOC_COVER_TITLE_FAMILY -+ -.COVER_TITLE_FONT .DOC_COVER_TITLE_FONT | like -.COVER_TITLE_COLOR .DOC_COVER_TITLE_COLOR | TITLE_ -.COVER_TITLE_SIZE .DOC_COVER_TITLE_SIZE -+ - -.COVER_CHAPTER_TITLE_FAMILY .DOC_COVER_CHAPTER_TITLE_FAMILY -+ -.COVER_CHAPTER_TITLE_FONT .DOC_COVER_CHAPTER_TITLE_FONT | like -.COVER_CHAPTER_TITLE_COLOR .DOC_COVER_CHAPTER_TITLE_COLOR | CHAPTER_TITLE_ -.COVER_CHAPTER_TITLE_SIZE .DOC_COVER_CHAPTER_TITLE_SIZE -+ - -.COVER_SUBTITLE_FAMILY .DOC_COVER_SUBTITLE_FAMILY -+ -.COVER_SUBTITLE_FONT .DOC_COVER_SUBTITLE_FONT | like -.COVER_SUBTITLE_COLOR .DOC_COVER_SUBTITLE_COLOR | SUBTITLE_ -.COVER_SUBTITLE_SIZE .DOC_COVER_AUTHOR_SIZE -+ - -.COVER_ATTRIBUTE_COLOR .DOC_COVER_ATTRIBUTE_COLOR - like ATTRIBUTE_COLOR - - the macro, .ATTRIBUTE_STRING, controls the attribution string - for both docheaders and cover pages; cover pages have no - separate ATTRIBUTE_STRING macro - -.COVER_AUTHOR_FAMILY .DOC_COVER_AUTHOR_FAMILY -+ -.COVER_AUTHOR_FONT .DOC_COVER_AUTHOR_FONT | like -.COVER_AUTHOR_COLOR .DOC_COVER_AUTHOR_COLOR | AUTHOR_ -.COVER_AUTHOR_SIZE .DOC_COVER_AUTHOR_SIZE -+ - -.COVER_DOCTYPE_FAMILY .DOC_COVER_DOCTYPE_FAMILY -+ -.COVER_DOCTYPE_FONT .DOC_COVER_DOCTYPE_FONT | like -.COVER_DOCTYPE_COLOR .DOC_COVER_DOCTYPE_COLOR | DOCTYPE_ -.COVER_DOCTYPE_SIZE .DOC_COVER_DOCTYPE_SIZE -+ - -.COVER_COPYRIGHT_FAMILY .DOC_COVER_COPYRIGHT_FAMILY -+ -.COVER_COPYRIGHT_FONT .DOC_COVER_COPYRIGHT_FONT | like any -.COVER_COPYRIGHT_COLOR .DOC_COVER_COPYRIGHT_COLOR | of the above -.COVER_COPYRIGHT_SIZE .DOC_COVER_COPYRIGHT_SIZE -+ -.COVER_COPYRIGHT_QUAD .DOC_COVER_COPYRIGHT_QUAD - - the copyright quad can be either L (left) or R (right); default is left - -.COVER_MISC_COLOR .DOC_COVER_MISC_COLOR - like any of the above _COLOR -.COVER_MISC_QUAD .DOC_COVER_MISC_QUAD - - the misc quad can be either L (left) or R (right); default is right -</pre> - -<strong>Note: COVER_MISC</strong> and -<strong>DOC_COVER_MISC</strong> have only two control macros, -<strong>_COLOR</strong> and <strong>_QUAD</strong>. The -family, font and size of the <kbd>MISC</kbd> argument to -<strong>COVER</strong> or <strong>DOC_COVER</strong> are always the -same as for <kbd>COPYRIGHT</kbd>. Should you wish the family, font -or size to be different from <kbd>COPYRIGHT</kbd>, I suggest setting -the type specs for <kbd>COPYRIGHT</kbd> to the ones you want for -<kbd>MISC</kbd>, then altering them for <kbd>COPYRIGHT</kbd> using -<a href="inlines.html#INDEX_INLINES">inline escapes</a> -in the -<a href="definitions.html#TERMS_STRINGARGUMENT">string argument</a> -you pass to the macro, -<a href="docprocessing.html#COPYRIGHT">COPYRIGHT</a>. (Of course, -you could always do the reverse, but if you pass several arguments -to -<a href="docprocessing.html#MISC">MISC</a>, -it's more likely you want to get <strong>MISC</strong> right first.) - -<p> -<hr> -<a href="refer.html#TOP">Next</a> -<a href="rectoverso.html#TOP">Prev</a> -<a href="#TOP">Top</a> -<a href="toc.html">Back to Table of Contents</a> -</body> -</html> |