From 8902e0ed6134c9ecc1177ef535852070d0e7326d Mon Sep 17 00:00:00 2001 From: simon Date: Thu, 25 Mar 2004 19:16:28 +0000 Subject: [PATCH] Obsoleted the `\preamble' command. Preamble text is now taken to be any ordinary displayable paragraph(s) appearing before the first chapter heading, meaning in particular that you can put lists, code paragraphs etc in preambles. Of course, `\preamble' is still supported for backwards compatibility, but it's now a zero-effect paragraph marker. git-svn-id: svn://svn.tartarus.org/sgt/halibut@3981 cda61777-01e9-0310-a592-d414129be87e --- bk_man.c | 34 ++++++++++---------- bk_text.c | 31 +++++++++--------- bk_whlp.c | 97 +++++++++++++++++++++++++++++---------------------------- bk_xhtml.c | 23 ++++++++------ doc/blurb.but | 8 ++--- doc/input.but | 26 ++++++---------- halibut.h | 1 - input.c | 6 ++-- inputs/test.but | 8 ++++- 9 files changed, 120 insertions(+), 114 deletions(-) diff --git a/bk_man.c b/bk_man.c index c464e84..1d39729 100644 --- a/bk_man.c +++ b/bk_man.c @@ -62,8 +62,8 @@ void man_backend(paragraph *sourceform, keywordlist *keywords, indexdata *idx) { paragraph *p; FILE *fp; - char const *sep; manconfig conf; + int done_copyright; IGNORE(keywords); /* we don't happen to need this */ IGNORE(idx); /* or this */ @@ -107,20 +107,7 @@ void man_backend(paragraph *sourceform, keywordlist *keywords, fprintf(fp, ".UC\n"); - /* Do the preamble and copyright */ - sep = ""; - for (p = sourceform; p; p = p->next) - if (p->type == para_Preamble) { - fprintf(fp, "%s", sep); - man_text(fp, p->words, TRUE, 0); - sep = "\n"; - } - for (p = sourceform; p; p = p->next) - if (p->type == para_Copyright) { - fprintf(fp, "%s", sep); - man_text(fp, p->words, TRUE, 0); - sep = "\n"; - } + done_copyright = FALSE; for (p = sourceform; p; p = p->next) switch (p->type) { /* @@ -132,7 +119,6 @@ void man_backend(paragraph *sourceform, keywordlist *keywords, case para_Biblio: /* only touch BiblioCited */ case para_VersionID: case para_Copyright: - case para_Preamble: case para_NoCite: case para_Title: break; @@ -145,6 +131,22 @@ void man_backend(paragraph *sourceform, keywordlist *keywords, case para_UnnumberedChapter: case para_Heading: case para_Subsect: + + if (!done_copyright) { + paragraph *p; + + /* + * The copyright comes just before the first chapter + * title. + */ + for (p = sourceform; p; p = p->next) + if (p->type == para_Copyright) { + fprintf(fp, ".PP\n"); + man_text(fp, p->words, TRUE, 0); + } + done_copyright = TRUE; + } + { int depth; if (p->type == para_Subsect) diff --git a/bk_text.c b/bk_text.c index 139e1d6..bde11bb 100644 --- a/bk_text.c +++ b/bk_text.c @@ -184,6 +184,7 @@ void text_backend(paragraph *sourceform, keywordlist *keywords, char *prefixextra; int nesting, nestindent; int indentb, indenta; + int done_copyright; IGNORE(keywords); /* we don't happen to need this */ IGNORE(idx); /* or this */ @@ -208,20 +209,9 @@ void text_backend(paragraph *sourceform, keywordlist *keywords, text_heading(fp, NULL, NULL, p->words, conf.atitle, conf.indent, conf.width); - /* Do the preamble and copyright */ - for (p = sourceform; p; p = p->next) - if (p->type == para_Preamble) - text_para(fp, NULL, NULL, p->words, - conf.indent_preambles ? conf.indent : 0, 0, - conf.width + (conf.indent_preambles ? 0 : conf.indent)); - for (p = sourceform; p; p = p->next) - if (p->type == para_Copyright) - text_para(fp, NULL, NULL, p->words, - conf.indent_preambles ? conf.indent : 0, 0, - conf.width + (conf.indent_preambles ? 0 : conf.indent)); - nestindent = conf.listindentbefore + conf.listindentafter; - nesting = 0; + nesting = (conf.indent_preambles ? 0 : -conf.indent); + done_copyright = FALSE; /* Do the main document */ for (p = sourceform; p; p = p->next) switch (p->type) { @@ -251,7 +241,6 @@ void text_backend(paragraph *sourceform, keywordlist *keywords, case para_Biblio: /* only touch BiblioCited */ case para_VersionID: case para_Copyright: - case para_Preamble: case para_NoCite: case para_Title: break; @@ -262,8 +251,22 @@ void text_backend(paragraph *sourceform, keywordlist *keywords, case para_Chapter: case para_Appendix: case para_UnnumberedChapter: + /* + * The copyright should come after the preamble but before + * the first chapter title. + */ + if (!done_copyright) { + paragraph *p; + + for (p = sourceform; p; p = p->next) + if (p->type == para_Copyright) + text_para(fp, NULL, NULL, p->words, + conf.indent + nesting, 0, conf.width - nesting); + done_copyright = TRUE; + } text_heading(fp, p->kwtext, p->kwtext2, p->words, conf.achapter, conf.indent, conf.width); + nesting = 0; break; case para_Heading: diff --git a/bk_whlp.c b/bk_whlp.c index 91b07c1..1d5dbc6 100644 --- a/bk_whlp.c +++ b/bk_whlp.c @@ -55,6 +55,7 @@ void whlp_backend(paragraph *sourceform, keywordlist *keywords, int i; int nesting; indexentry *ie; + int done_contents_topic; filename = "output.hlp"; /* FIXME: configurability */ cntname = "output.cnt"; /* corresponding contents file */ @@ -144,8 +145,7 @@ void whlp_backend(paragraph *sourceform, keywordlist *keywords, whlp_prepare(h); /* ------------------------------------------------------------------ - * Do the contents page, containing title, preamble and - * copyright. + * Begin the contents page. */ whlp_begin_topic(h, contents_topic, "Contents", "DB(\"btn_up\")", NULL); @@ -173,51 +173,6 @@ void whlp_backend(paragraph *sourceform, keywordlist *keywords, /* FIXME: configurability in that string */ } - /* - * Next comes the preamble, which just goes into the ordinary - * scrolling region. - */ - for (p = sourceform; p; p = p->next) { - if (p->type == para_Preamble) { - whlp_para_attr(h, WHLP_PARA_SPACEBELOW, 12); - whlp_begin_para(h, WHLP_PARA_SCROLL); - whlp_mkparagraph(&state, FONT_NORMAL, p->words, FALSE); - whlp_end_para(h); - } - } - - /* - * The copyright goes to two places, again: into the contents - * page and also into the system section. - */ - { - rdstringc rs = {0, 0, NULL}; - for (p = sourceform; p; p = p->next) { - if (p->type == para_Copyright) { - whlp_para_attr(h, WHLP_PARA_SPACEBELOW, 12); - whlp_begin_para(h, WHLP_PARA_SCROLL); - whlp_mkparagraph(&state, FONT_NORMAL, p->words, FALSE); - whlp_end_para(h); - whlp_rdaddwc(&rs, p->words); - } - } - if (rs.text) { - whlp_copyright(h, rs.text); - sfree(rs.text); - } - } - - /* - * Now do the primary navigation menu. - */ - for (p = sourceform; p; p = p->next) { - if (p->type == para_Chapter || - p->type == para_Appendix || - p->type == para_UnnumberedChapter) - whlp_navmenu(&state, p); - } - - state.curr_topic = contents_topic; lastsect = NULL; /* ------------------------------------------------------------------ @@ -235,7 +190,6 @@ void whlp_backend(paragraph *sourceform, keywordlist *keywords, case para_Biblio: /* only touch BiblioCited */ case para_VersionID: case para_Copyright: - case para_Preamble: case para_NoCite: case para_Title: break; @@ -258,6 +212,53 @@ void whlp_backend(paragraph *sourceform, keywordlist *keywords, case para_UnnumberedChapter: case para_Heading: case para_Subsect: + + if (!done_contents_topic) { + paragraph *p; + + /* + * If this is the first section title we've seen, then + * we're currently still in the contents topic. We + * should therefore finish up the contents page by + * writing the copyright notice and a nav menu. + */ + + /* + * The copyright goes to two places, again: into the + * contents page and also into the system section. + */ + { + rdstringc rs = {0, 0, NULL}; + for (p = sourceform; p; p = p->next) { + if (p->type == para_Copyright) { + whlp_para_attr(h, WHLP_PARA_SPACEBELOW, 12); + whlp_begin_para(h, WHLP_PARA_SCROLL); + whlp_mkparagraph(&state, FONT_NORMAL, p->words, FALSE); + whlp_end_para(h); + whlp_rdaddwc(&rs, p->words); + } + } + if (rs.text) { + whlp_copyright(h, rs.text); + sfree(rs.text); + } + } + + /* + * Now do the primary navigation menu. + */ + for (p = sourceform; p; p = p->next) { + if (p->type == para_Chapter || + p->type == para_Appendix || + p->type == para_UnnumberedChapter) + whlp_navmenu(&state, p); + } + + state.curr_topic = contents_topic; + + done_contents_topic = TRUE; + } + if (lastsect && lastsect->child) { paragraph *q; /* diff --git a/bk_xhtml.c b/bk_xhtml.c index 449eb4e..b2bed07 100644 --- a/bk_xhtml.c +++ b/bk_xhtml.c @@ -580,7 +580,7 @@ static void xhtml_ponder_layout(paragraph *p) static void xhtml_do_index(); static void xhtml_do_file(xhtmlfile *file); static void xhtml_do_top_file(xhtmlfile *file, paragraph *sourceform); -static void xhtml_do_paras(FILE *fp, paragraph *p); +static void xhtml_do_paras(FILE *fp, paragraph *p, paragraph *end); static int xhtml_do_contents_limit(FILE *fp, xhtmlfile *file, int limit); static int xhtml_do_contents_section_limit(FILE *fp, xhtmlsection *section, int limit); static int xhtml_add_contents_entry(FILE *fp, xhtmlsection *section, int limit); @@ -875,11 +875,15 @@ static void xhtml_do_top_file(xhtmlfile *file, paragraph *sourceform) /* Do the preamble and copyright */ for (p = sourceform; p; p = p->next) { - if (p->type == para_Preamble) - { - fprintf(fp, "

"); - xhtml_para(fp, p->words); - fprintf(fp, "

\n"); + if (p->type == para_Chapter || p->type == para_Heading || + p->type == para_Subsect || p->type == para_Appendix || + p->type == para_UnnumberedChapter) { + /* + * We've found the end of the preamble. Do every normal + * paragraph up to there. + */ + xhtml_do_paras(fp, sourceform, p); + break; } } for (p = sourceform; p; p = p->next) @@ -1067,14 +1071,14 @@ static void xhtml_do_sections(FILE *fp, xhtmlsection *sections) { while (sections) { currentsection = sections; - xhtml_do_paras(fp, sections->para); + xhtml_do_paras(fp, sections->para, NULL); xhtml_do_sections(fp, sections->child); sections = sections->next; } } /* Write this list of paragraphs. Close off all lists at the end. */ -static void xhtml_do_paras(FILE *fp, paragraph *p) +static void xhtml_do_paras(FILE *fp, paragraph *p, paragraph *end) { int last_type = -1, ptype, first=TRUE; stack lcont_stack = stk_new(); @@ -1082,7 +1086,7 @@ static void xhtml_do_paras(FILE *fp, paragraph *p) return; /* for (; p && (xhtml_para_level(p)>limit || xhtml_para_level(p)==-1 || first); p=p->next) {*/ - for (; p && (xhtml_para_level(p)==-1 || first); p=p->next) { + for (; p && p != end && (xhtml_para_level(p)==-1 || first); p=p->next) { first=FALSE; switch (ptype = p->type) { @@ -1095,7 +1099,6 @@ static void xhtml_do_paras(FILE *fp, paragraph *p) case para_Biblio: /* only touch BiblioCited */ case para_VersionID: case para_Copyright: - case para_Preamble: case para_NoCite: case para_Title: break; diff --git a/doc/blurb.but b/doc/blurb.but index 2bb59b1..b644681 100644 --- a/doc/blurb.but +++ b/doc/blurb.but @@ -8,12 +8,12 @@ \cfg{xhtml-body-end}{Comments to anakin@pobox.com} -\preamble Halibut is a free (MIT-licensed) documentation production -system, able to generate multiple output formats from the same input -data. +Halibut is a free (MIT-licensed) documentation production system, +able to generate multiple output formats from the same input data. +This document is its user manual. \copyright This manual is copyright 2004 Simon Tatham. All rights reserved. You may distribute this documentation under the MIT licence. See \k{licence} for the licence text in full. -\versionid $Id: blurb.but,v 1.1 2004/03/25 18:33:02 simon Exp $ +\versionid $Id: blurb.but,v 1.2 2004/03/25 19:16:28 simon Exp $ diff --git a/doc/input.but b/doc/input.but index e5c157b..587836f 100644 --- a/doc/input.but +++ b/doc/input.but @@ -867,16 +867,16 @@ These sometimes occur in books, for specialist purposes such as keyword argument, because there is no sensible way to generate an automatic cross-reference to such a chapter anyway. -\S{input-blurb} \c{\\preamble}, \c{\\copyright}, \c{\\title}, -\c{\\versionid}: Miscellaneous blurb commands +\S{input-blurb} \c{\\copyright}, \c{\\title}, \c{\\versionid}: +Miscellaneous blurb commands -These four commands define a variety of special paragraph types. +These three commands define a variety of special paragraph types. They are all used in the same way: you put the command at the start of a paragraph, and then just follow it with normal text, like this: \c \title My First Manual -The four special paragraph types are: +The three special paragraph types are: \dt \c{\\title} @@ -885,23 +885,15 @@ title is treated specially in some output formats (for example, it's used in a \cw{} tag in the HTML output), so it needs a special paragraph type to point it out. -\dt \c{\\preamble} - -\dd This command indicates ordinary text that appears \e{before} the -first chapter heading. \#{FIXME: figure out what Halibut actually -does do with ordinary text before a chapter heading. Then figure out -whether that's sensible. Then figure out what \preamble has to offer -that's perceptibly different. Fix if necessary.} - \dt \c{\\copyright} \dd This command indicates that the paragraph attached to it contains a copyright statement for the document. This text is -usually displayed inline, in the same way as \c{\\preamble} text, -but in some output formats it is given additional special treatment. -For example, Windows Help files have a standard slot in which to -store a copyright notice, so that other software can display it -prominently. +usually displayed inline, just before the first chapter title but +after any preamble text before that; but in some output formats it +is given additional special treatment. For example, Windows Help +files have a standard slot in which to store a copyright notice, so +that other software can display it prominently. \dt \c{\\versionid} diff --git a/halibut.h b/halibut.h index c771459..71087c4 100644 --- a/halibut.h +++ b/halibut.h @@ -105,7 +105,6 @@ enum { para_Description, para_Code, para_Copyright, - para_Preamble, para_NoCite, para_Title, para_VersionID, diff --git a/input.c b/input.c index db862dd..9d165fa 100644 --- a/input.c +++ b/input.c @@ -190,7 +190,7 @@ enum { c_lcont, /* continuation para(s) for list item */ c_n, /* numbered list */ c_nocite, /* bibliography trickery */ - c_preamble, /* document preamble text */ + c_preamble, /* (obsolete) preamble text */ c_q, /* quote marks */ c_quote, /* block-quoted paragraphs */ c_rule, /* horizontal rule */ @@ -259,7 +259,7 @@ static void match_kw(token *tok) { {"lcont", c_lcont}, /* continuation para(s) for list item */ {"n", c_n}, /* numbered list */ {"nocite", c_nocite}, /* bibliography trickery */ - {"preamble", c_preamble}, /* document preamble text */ + {"preamble", c_preamble}, /* (obsolete) preamble text */ {"q", c_q}, /* quote marks */ {"quote", c_quote}, /* block-quoted paragraphs */ {"rule", c_rule}, /* horizontal rule */ @@ -766,7 +766,7 @@ static void read_file(paragraph ***ret, input *in, indexdata *idx) { case c_define: is_macro = TRUE; needkw = 1; break; /* For \nocite the keyword is _everything_ */ case c_nocite: needkw = 8; par.type = para_NoCite; break; - case c_preamble: needkw = 32; par.type = para_Preamble; break; + case c_preamble: needkw = 32; par.type = para_Normal; break; case c_rule: needkw = 16; par.type = para_Rule; break; case c_title: needkw = 32; par.type = para_Title; break; case c_versionid: needkw = 32; par.type = para_VersionID; break; diff --git a/inputs/test.but b/inputs/test.but index cfefbdb..683d19b 100644 --- a/inputs/test.but +++ b/inputs/test.but @@ -6,10 +6,16 @@ Lines, Not Just Two. How's That For Ludicrous? \cfg{xhtml-leaf-contains-contents}{true} \cfg{man-headnumbers}{true} +This paragraph is not labelled \q{preamble}, but should still appear +as it. + \preamble This manual is a small joke effort, designed to use every feature \#{ comment } that Halibut's input format supports. Creation date \date{%Y.%m.%d} (default format is \date). +\c Here is a code paragraph in the preamble, just to stress that all +\c things are possible. Ooh! + \copyright Copyright 1999 Simon \#{second comment}Tatham. All rights reserved. @@ -19,7 +25,7 @@ a bit] \define{coopt} co\u00F6{-o}pt -\versionid $Id: test.but,v 1.21 2004/03/24 19:23:21 simon Exp $ +\versionid $Id: test.but,v 1.22 2004/03/25 19:16:28 simon Exp $ \C{ch\\ap} First chapter title; for similar wrapping reasons this chapter title will be ludicrously long. I wonder how much more -- 2.11.0