added docinfo header and footer section

- how to create docinfo file - how to name docinfo file - set docinfo attributes - substitute attributes in docinfo file - related to asciidoctor#88 - related to asciidoctor/asciidoctor#116 - related to asciidoctor/asciidoctor#403 - related to asciidoctor/asciidoctor#486
graphitefriction · Sep 10, 2013 · c61f028 · c61f028
1 parent 9767f3d
commit c61f028
Showing 1 changed file with 181 additions and 10 deletions.
diff --git a/docs/user-manual.adoc b/docs/user-manual.adoc
@@ -22,6 +22,7 @@ Sarah White <https://github.com/graphitefriction[@graphitefriction]>; Dan Allen
 :prettify-ref: https://code.google.com/p/google-code-prettify
 :fontawesome-ref: http://fortawesome.github.io/Font-Awesome
 :issue-ref: https://github.com/asciidoctor/asciidoctor/issues
+:richfaces-docinfo: https://github.com/richfaces/richfaces-docs/blob/master/Developer_Guide/src/main/docbook/en-US/Developer_Guide-docinfo.xml
 
 [NOTE]
 .This document is under active development and discussion!
@@ -799,30 +800,200 @@ Local date and time when rendered
 
 Local time when rendered
 
-=== Docinfo files
+=== Docinfo file
 
-You can include custom content in the header of the output document (HTML or DocBook) by supplying docinfo files.
-In Asciidoctor 0.1.4, docinfo files can be used to add custom content to the footer as well.
+You can add custom content to the header or footer of a document with document information (+docinfo+) files.
+The docinfo file's content and file extension depends on whether the source document's output is HTML or DocBook.
+
+==== Creating a docinfo file
+
+When the source document will be rendered to HTML, the docinfo file can contain the elements allowed in an HTML +<HEAD>+ section, including:
+
+* +<base>+
+* +<link>+
+* +<meta>+
+* +<noscript>+
+* +<script>+
+* +<style>+
+* +<title>+
+
+As seen in the example below, docinfo files are useful for storing metadata, stylesheet, and script information.
+Note that you do not need to include the +<head>+ tag, nor is the +<title>+ tag required.
+
+.A docinfo file for HTML output
+[source,html]
+----
+<meta name="keywords" content="open source, documentation">
+<meta name="description" content="The dangerous and thrilling adventures of an open source documentation team.>
+<link rel="stylesheet" href="basejump.css">
+<script src="map.js"></script>
+----
+
+Docinfo files for HTML output must be saved with the +.html+ file extension.
+
+When DocBook 5.0 is the rendered output, the docinfo file may include any of the http://www.docbook.org/tdg5/en/html/info.html[+<info>+ element's 48 children], such as:
+
+* +<address>+
+* +<copyright>+
+* +<edition>+
+* +<keywordset>+
+* +<publisher>+
+* +<subtitle>+
+
+The following example shows some of the content a docinfo file for DocBook might contain.
+
+.A docinfo file for DocBook 5.0 output
+[source,xml]
+----
+<author>
+  <personname>
+    <firstname>Karma</firstname>
+    <surname>Chameleon</surname>
+  </personname>
+  <affiliation>
+    <jobtitle>Word SWAT Team Leader</jobtitle>
+  </affiliation>
+</author>
+
+<keywordset>
+  <keyword>open source</keyword>
+  <keyword>documentation</keyword>
+  <keyword>adventure</keyword>
+</keywordset>
+
+<printhistory>
+  <para>April, 2019. Twenty-sixth printing.
+  </para>
+</printhistory>
+----
+
+Docinfo files for DocBook output must be saved with the +.xml+ file extension.
+To see another example of a docinfo file for DocBook, checkout the {richfaces-docinfo}[RichFaces Developer Guide docinfo file].
+
+==== Docinfo attributes and file names
+
+To add content from a docinfo file to the header of a rendered document:
+
+. The docinfo file must be named correctly
+. The appropriate docinfo attribute must be set in the source document
+
+How you name your docinfo file and the docinfo attribute you set in your source document depends on whether you want to add content to:
+
+[loweralpha]
+. a specific document
+. all the documents in a directory
+. a and b
+
+The attributes and the corresponding file names are listed in the table below.
+
+.Docinfo attributes and file names
+|===
+|Attribute |Purpose |docinfo file name for HTML |docinfo file name for DocBook
+
+|docinfo
+|Add content to a specific document
+|+<docname>-docinfo.html+ 
+|+<docname>-docinfo.xml+
+
+|docinfo1
+|Add content to all documents in the same directory
+|+<docname>.html+ 
+|+<docname>.xml+
+
+|docinfo2
+|Add content from either docinfo file
+|+<docname>.html+, +<docname>-docinfo.html+  
+|+<docname>.xml+, +<docname>-docinfo.xml+
+|===
+
+Let's apply the information above to an example exercise.
+
+You have two AsciiDoc documents, +adventure.adoc+ and +insurance.adoc+, saved in the same folder.
+You want to add the same content to the headers of both documents when they're rendered to HTML.
+
+. Create a docinfo file using +<head>+ elements.
+. Save the docinfo file as +docinfo.html+.
+. Set the +docinfo1+ attribute in +adventure.adoc+ and +insurance.adoc+.
+
+You also want to include some additional content to the header of +adventure.adoc+.
+
+. Create *another* docinfo file using +<head>+ elements.
+. Save the docinfo file as +adventure-docinfo.html+.
+. Set the +docinfo+ attribute in +adventure.adoc+.
+. Alternatively, you could remove the +docinfo1+ attribute and set +docinfo2+ instead.
+
+==== Footer docinfo files
 
 Footer docinfo files are differentiated from header docinfo files by adding +-footer+ to the file name.
 In the HTML output, the footer content is inserted inside the footer div (i.e., +<div id="footer">+).
 In the DocBook output, the footer content is inserted immediately before the ending +</article>+ or +</book>+ element.
 
+[horizontal]
 .docinfo
 If you want to add content to the footer of a specific document, put the content in the file +<docname>-footer.html+ (for HTML output) or +<docname>-footer.xml+ (for DocBook output), where +<docname>+ is the name of the document without the AsciiDoc extension.
-Then, set the attribute +docinfo+ in the AsciiDoc source document to enable the feature.
+Then, set the attribute +docinfo+ in the source document.
 
 .docinfo1
-If you want to add content to the footer of all documents in the same directory, put the content in the file +docinfo-footer.html+ (for HTML output) or +docinfo-footer.xml+ (for DocBook output).
-Then, set the attribute +docinfo1+ in the AsciiDoc source document to enable the feature.
+If you want to add content to the footer of all documents in the same directory, put the content in the file +docinfo-footer.html+ or +docinfo-footer.xml+.
+Then, set the attribute +docinfo1+ in the source document to enable the feature.
 
 .docinfo2
-If you want the document to look for either docinfo file, set the attribute +docinfo2+ in the AsciiDoc source document.
+If you want the document to look for either docinfo file, set the attribute +docinfo2+ in the source document.
+
+TIP: The "Last updated" line in the footer can be disabled by unassigning the attribute +last-update-label+.
+
+==== Attribute substitution
+
+Docinfo files can include attribute references.
 
-Additional enhancements:
+For example, if you created the following docinfo file:
 
-* Attributes are substituted in the content of docinfo files (both header and footer).
-* The "Last updated" line in the footer can be disabled by unassigning the attribute +last-update-label+.
+.Docinfo file containing a +revnumber+ attribute reference
+[source,xml]
+----
+<edition>{revnumber}</edition>
+----
+
+And this source document:
+
+.Source document including a revision number
+----
+= Document Title
+Author Name
+v1.0, 2013-06-01
+:doctype: book
+:backend: docbook
+:docinfo:
+----
+
+Then the rendered DocBook output would be:
+
+[source,xml]
+----
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+    "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<book lang="en">
+  <bookinfo>
+    <title>Document Title</title>
+    <date>2013-06-01</date>
+    <author>
+      <firstname>Author</firstname>
+      <surname>Name</surname>
+    </author>
+    <authorinitials>AN</authorinitials>
+    <revhistory>
+      <revision>
+        <revnumber>1.0</revnumber>
+        <date>2013-06-01</date>
+        <authorinitials>AN</authorinitials>
+      </revision>
+    </revhistory>
+<edition>1.0</edition> <1>
+  </bookinfo>
+</book>
+----
+<1> The +revnumber+ attribute reference was replaced by the source document's revision number in the rendered output.
 
 == Table of Contents