Scribe to HTML: Making A Structured HTML Document

Producing HTML Documents with Scribe

3. Making A Structured HTML Document

By including the library file:

@libraryfile(HTML)

in addition to specifying the HTML device, you can produce structured HTML documents, with inter-file links set up automatically. This command should be included after all document setup commands, such as @generate, @disable, and @style.

The resulting document is structured as follows:

Each Chapter and Section produces a separate HTML file. The HTML <TITLE> tag is inserted automatically. If needed, you can specify "inline" Chapters and Sections that don't start new files.
Each HTML file contains, at the very beginning, PREVIOUS and NEXT hypertext links, pointing at the adjacent sections. Chapters also contain PREVIOUS CHAPTER and NEXT CHAPTER links. These links appear as buttons.
Each Chapter contains, at the beginning, a table of contents with hypertext links to the individual sections.

To achieve these results, the following changes must be made to the Scribe manuscript file:

Add information to the document to construct the hypertext links. This consists of augmenting the @Chapter and @Section commands to include a tag, which will be used by both Scribe and HTML for cross-references.
Add a postprocessing step that splits the Scribe-generated .html file into separate .html files.

The following sections describe these changes in detail.

3.1. Coexistence With Other Device Types

Once you've made the changes described below, you will still be able to format your document for other devices. For devices other than HTML, the HTML library contains "stub" definitions for the new commands that duplicate the behavior of the regular Scribe commands.

Summary: You can do all of the fancy HTML formatting you want, and you'll still be able to format for other devices, without changing your document.

3.2. Convert @Section to @MakeSection

Each @Section command should be converted to @MakeSection:

@MakeSection(tag=tag, title="Title of the Section")

This will start a new HTML file named tag.html at this point. If you want to continue the same file (for example, if you have several short sections), you can use the @MakeInlineSection command:

@MakeInlineSection(tag=tag, title="Title of the Section")

If you use other section-level sectioning commands, such as @PrefaceSection, you can give an additional parameter to the @MakeSection or @MakeInlineSection command:

@MakeSection(tag=tag, title="Title of the Section",
        command=PrefaceSection)

3.3. Convert @Chapter to @MakeChapter

If your document doesn't contain chapters, skip this part, and make sure that you specify "nochapters" to the @MakeDocument command.

Each @Chapter command should be converted to @MakeChapter:

@MakeChapter(tag=tag, title="Title of the Chapter")

This will start a new HTML file named tag.html at this point. If you want to continue the same file (for example, if there is very little introductory material before the first real chapter) you can use the @MakeInlineChapter command:

@MakeInlineChapter(tag=tag, title="Title of the Chapter")

If you use other chapter-level sectioning commands, such as @Appendix or @UnNumbered, you can give an additional parameter to the @MakeChapter or @MakeInlineChapter command:

@MakeChapter(tag=tag, title="Title of the Chapter",
        command=UnNumbered)

3.4. Add @MakeDocument at the Beginning

@MakeDocument is very similar to @MakeChapter, except that it doesn't actually start a chapter. It does determine the name of the first HTML generated. It should be placed before any text in the .mss file.

@MakeDocument(tag=tag, title="Title of the Whole Document")

We use a convention that the name of the top-level document in a directory is home.html. So, the tag in the @MakeDocument command would be "home.html".

There are two options that may be specified in the @MakeDocument command:

NoChapters: Specifies that no chapters will be used. This causes the chapter forward/back buttons to be omitted.
NoSections: Specifies that the document will not use @MakeSection or @MakeChapter commands, so it will be a single HTML file. No forward/back buttons (either for sections or chapters) will be produced.

For example:

@MakeDocument(tag=home.html, title="Document Title", nochapters)

3.5. Include @generate Commands for Each Chapter

The section cross references for each chapter are stored in Scribe "generated portions," each named after the chapter tag. This is the same mechanism that Scribe uses for the tables of contents. For a document named "test.mss" with a @MakeChapter(tag=intro, ...), the chapter contents for that chapter would be stored in a file named "test.intro".

Each of these generated portions requires a command to be added to the beginning of the .mss file. For each @MakeChapter, insert a line of the form:

@generate(tag=tag)

before the @LibraryFile(HTML) command.

If you add a chapter and forget the @generate command, Scribe will produce some very cryptic error messages:

Error in BACKPLACE command found while processing the manuscript.
res-html.mss, line 123:  @backplace(resources)
The name RESOURCES should be defined but is not!

Error in BACKPLACE command.
res-html.mss, line 123:  @backplace(resources)
Portion RESOURCES cannot be backplaced.

3.6. Forced Line Breaks -- Convert @* to @br

The @* command has no effect for the HTML device, except in unfilled environments. As an alternative, the HTML library defines the @br command, which causes a line break for all device types.

You should use @br in place of @*.

3.7. Add an @HTMLfinish Command at the End

At the very end of your .mss file, add the command:

@HTMLfinish()

If you leave out this command, you will get two error messages for the last chapter and section tags:

Error in VALUE command found while processing the manuscript.
other.mss, line 241:  @value(tag-next)
The name tag-next is used in the @Value command, but it has not been defined
with @String.

Glenn Trewitt, trewitt@pa.dec.com