Changes between Initial Version and Version 1 of DocsOrganization

Timestamp:

Jun 28, 2007, 1:24:47 PM (15 years ago)

Author:

Matias Capeletto

Comment:

--

DocsOrganization

@@ +1 @@
+
+'''[#example_boostbook Docbook source]''' - ''Required''
+
+  * '''[#example_boostbook_xml doc/lib_name.xml]'''
+    [[Br]] Doc source in docbook format. Optionally it can include boostbook extensions.
+  * '''[#example_boostbook_xsl doc/lib_name.xsl]'''
+    [[Br]] Library dependents output configuration parameters (i.e. chunker depth).
+  * '''[#example_boostbook_jamfile doc/Jamfile.v2]'''
+    [[Br]] "doc/bjam --v2" will generate the HTML docs.
+
+'''[#example_quickbook Quickbook Source]''' - ''Optional''
+
+  * '''[#example_quickbook_main_qbk doc/lib_name.qbk]'''
+    [[Br]] Main quickbook file.
+  * '''[#example_quickbook_moderate_section_qbk doc/*.qbk]'''
+    [[Br]] Moderate size main sections quickbook files
+  * '''[#example_doc_example_qbk doc/larger_section.qbk]'''
+  * '''[#example_doc_example_qbk doc/larger_section/*.qbk]'''
+    [[Br]] Large size main sections (i.e reference) may be splitted again, organizing them 
+    in a directory tree to avoid cluttering the  '''doc''' directory.
+
+'''[http://en.wikipedia.org/wiki/Category:Graphics_file_formats Images]''' - ''Optional''
+
+  * '''[http://en.wikipedia.org/wiki/PNG doc/images/*.png]'''
+    [[Br]] You can use other formats, but be a good web citizen and use portable networks graphics.
+  * '''[http://en.wikipedia.org/wiki/Scalable_Vector_Graphics doc/images/*.svg]'''
+    [[Br]] If you intend to have a decent rendering in the pdf docs, use svg.
+
+'''[#example_doc_example Examples]''' - ''Optional''
+
+  * '''[#example_doc_example_cpp example/doc/*.cpp]'''
+    [[Br]] Quickbook allows us to import code chunks, instead of hard-coding them in the qbk source.
+    This allow as to be sure that every code example will be in sync and with out typos. 
+  * '''[#example_doc_example_jamfile example/doc/Jamfile.v2]'''
+    [[Br]] Testsuite for the doc examples.
+
+'''[#example_navigation Navigation aid]''' - ''Will be automated in the future''
+
+  * '''[#example_navigation_sections_xml doc/html/sections.xml]'''
+    [[Br]] Nested links xml definition of the library sections. This file is used to generate the 
+    navigation select boxes and tree sidebar (''expected it soon'').
+
+----
+
+=== Library docs organization example ===
+
+[[PageOutline(4-5,Examples list,inline)]]
+
+==== Docbook source ==== #example_boostbook
+
+===== doc/lib_name.xml ===== #example_boostbook_xml
+
+Doc source in docbook format. Optionally it can include boostbook extensions.
+{{{
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
+<library id="library_name" name="Boost.LibraryName" dirname="library_name" last-revision="$Date: 2007/06/14 22:18:40 $"
+ xmlns:xi="http://www.w3.org/2001/XInclude">
+
+  <libraryinfo>
+    <author>
+      <firstname>name</firstname> <surname>name</surname>
+    </author>
+    <copyright>
+      <year>year</year> <holder>name</holder>
+    </copyright>
+    <legalnotice>
+      <para>
+        Distributed under the Boost Software License, Version 1.0. (See accompanying
+        file LICENSE_1_0.txt or copy at 
+        <ulink url="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</ulink>)
+      </para>
+    </legalnotice>
+    <librarypurpose>
+      Standard boostbook example
+    </librarypurpose>
+    <librarycategory name="category:library_category"></librarycategory>
+  </libraryinfo>
+
+  <title>Boost.LibraryName</title>
+
+  <section id="library_name.section_id">
+
+    <title>Section Title</title>
+
+    <para>
+      This is an example of a <emphasis role="bold">standard</emphasis> Boostbook document. 
+      An <ulink url="http://www.boost.org">external link</ulink>
+    </para>
+
+    <para>
+      These should be syntax highlighted:
+    </para>
+  
+    <programlisting>
+<phrase role="preprocessor">#include</phrase> <phrase role="special">&lt;</phrase><phrase role="identifier">iostream</phrase><phrase role="special">&gt;</phrase>
+
+<phrase role="keyword">int</phrase> <phrase role="identifier">main</phrase><phrase role="special">()</phrase>
+<phrase role="special">{</phrase>
+    <phrase role="comment">// Sample code
+</phrase>    <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase> <phrase role="special">&lt;&lt;</phrase> <phrase role="string">&quot;Hello, World\n&quot;</phrase><phrase role="special">;</phrase>
+    <phrase role="keyword">return</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase>
+<phrase role="special">}</phrase>
+
+    </programlisting>
+
+  </section>
+
+</library>
+}}}
+
+===== doc/lib_name.xsl ===== #example_boostbook_xsl
+
+Library dependents output configuration parameters (i.e. chunker depth).
+{{{
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+   Copyright (c) Year author name, author name
+
+   Distributed under the Boost Software License, Version 1.0.
+   (See accompanying file LICENSE_1_0.txt or copy at
+   http://www.boost.org/LICENSE_1_0.txt)
+                                                                   -->
+
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+                version="1.0">
+
+  <!-- HTML Boostbook parameters -->
+
+  <xsl:param name = "chapter.logo.img"             select = "'../images/library_logo.png'" />
+
+  <xsl:param name = "quickbook.source.style.show"  select = "'true'" />
+
+  <!-- HTML Dockbook parameters -->
+
+  <xsl:param name = "chunk.section.depth"          select = "2" />
+
+</xsl:stylesheet>
+}}}
+
+===== doc/Jamfile.v2 ===== #example_boostbook_jamfile
+
+"doc/bjam --v2" will generate the html docs.
+{{{
+# Boost.LibraryName
+#
+# Copyright (c) Years author name, author name
+#
+# Distributed under the Boost Software License, Version 1.0.
+# (See accompanying file LICENSE_1_0.txt or copy at
+# http://www.boost.org/LICENSE_1_0.txt)
+
+using quickbook ;
+
+xml library_name 
+    : 
+        library_name.qbk ;
+
+
+boostbook standalone
+    :
+        library_name
+    :
+        library_name.xsl
+    ;
+}}}
+
+==== Quickbook Source ==== #example_quickbook
+
+===== doc/lib_name.qbk ===== #example_quickbook_main_qbk
+
+Main quickbook file.
+{{{
+[library LibraryName
+    [quickbook 1.4]
+    [copyright Year author name, author name]
+    [purpose Standard qbk example]
+    [id library_name]
+    [dirname library_name]
+    [license
+        Distributed under the Boost Software License, Version 1.0.
+        (See accompanying file LICENSE_1_0.txt or copy at
+        [http://www.boost.org/LICENSE_1_0.txt])
+    ]
+    [authors [surname, firstname], [surname, firstname] ]
+    [category library_category]
+]
+
+[/ Templates ]
+
+[/ Images ]
+
+[template Diagram [$../images/diagram.png]]
+
+[/ External Links ]
+
+[template SgiAssignable [@http://www.sgi.com/tech/stl/Assignable.html Assignable]]
+
+[/ Sections ]
+
+[section Small Section]
+
+A few lines.
+A nice diagram of the lib:
+[Diagram]
+
+[endsect]
+
+[/ Moderate section abstract ]
+[include moderate_size_section.qbk]
+
+[/ Larger section abstract ]
+[include larger_size_section.qbk]
+
+[section Other Small Section]
+
+Some more lines.
+An external resource: [SgiAssignable]
+
+[endsect]
+}}}
+
+===== doc/moderate_section.qbk ===== #example_quickbook_moderate_section_qbk
+
+Moderate size main sections quickbook files
+{{{
+[/
+    Boost.LibrayName
+    Copyright (c)  Year author name
+
+    Distributed under the Boost Software License, Version 1.0.
+    (See accompanying file LICENSE_1_0.txt or copy at
+    http://www.boost.org/LICENSE_1_0.txt)
+]
+
+[/ QuickBook Document version 1.4 ]
+
+[/ Section specifics templates ]
+
+[template ModerateSizeImage [$../images/moderate_size_image.svg]
+
+[/ Sections ]
+
+[section Moderate section]
+
+You can use this sections templates to show an image:
+[ModerateSizeImage]
+
+Main templates are allowed too, reuse [SgiAssignable].
+
+A nice table, including marketting stuff
+
+[table Quickbook Rocks
+
+[[Feature              ][Purpose                                   ]]
+
+[[Templates            ][Extensibility and constants               ]]
+[[Code import          ][Code consistency, callouts and reuse      ]]
+[[Wiki style formating ][High signal to noise ratio in source code ]]
+[[Internal links       ][Easy to use inter-doc anchors             ]]
+[[Syntax Highlighting  ][Both in code blocks and in `inline code`  ]]
+
+]
+
+[endsect]
+}}}
+
+==== Doc Examples ==== #example_doc_example
+
+===== example/doc/code_example.cpp ===== #example_doc_example_cpp
+
+Quickbook allows us to import code chunks, instead of hard-coding them in the qbk source.
+This allow as to be sure that every code example will be in sync and with out typos. 
+{{{
+// Boost.LibraryName
+//
+// Copyright (c) Year author name, author name
+//
+// Distributed under the Boost Software License, Version 1.0.
+// (See accompanying file LICENSE_1_0.txt or copy at
+// http://www.boost.org/LICENSE_1_0.txt)
+
+// Doc example
+
+#include <string>
+#include <iostream>
+
+//[ DocCodeFunctionName
+
+std::string greeting()
+{
+    return "Hello world!";
+}
+
+//]
+
+//[ DocCodeExampleName
+
+int main()
+{
+    /*<< A callout bug >>*/
+    std::string message = greeting();
+    std::cout << message; /*< Inlined callout bug >*/
+}
+
+//]
+}}}
+
+===== doc/larger_section.qbk ===== #example_doc_example_qbk
+
+{{{
+[/
+    Boost.LibrayName
+    Copyright (c) Year author name
+
+    Distributed under the Boost Software License, Version 1.0.
+    (See accompanying file LICENSE_1_0.txt or copy at
+    http://www.boost.org/LICENSE_1_0.txt)
+]
+
+[/ QuickBook Document version 1.4 ]
+
+[/ Section specifics code ]
+
+[import ../example/doc/example_name.cpp]
+
+[/ Sections ]
+
+[section Larger section]
+
+[section Introduction]
+
+A few lines.
+We can easily use the imported code:
+
+[DocCodeFunctionName]
+
+And then the main function
+
+[DocCodeExampleName]
+
+That is it!
+
+[endsect]
+
+[include larger_section/subsection_name.qbk]
+
+[endsect]
+}}}
+
+===== example/doc/Jamfile.v2 ===== #example_doc_example_jamfile
+
+Testsuite for the doc examples.
+{{{
+# Boost.LibraryName
+#
+# Copyright (c) Years author name, author name
+#
+# Distributed under the Boost Software License, Version 1.0.
+# (See accompanying file LICENSE_1_0.txt or copy at
+# http://www.boost.org/LICENSE_1_0.txt)
+
+import testing ;
+
+test-suite "doc_code"
+    :
+    [ compile       compilable_example.cpp      ]
+    [ run           runable_example.cpp         ]
+    [ compile-fail  compile_fail_example.cpp    ]
+    ;
+}}}
+
+==== Navigation aid ==== #example_navigation
+
+===== doc/html/sections.xml ===== #example_navigation_sections_xml
+
+Nested links xml definition of the library sections. This file is used to generate the 
+navigation select boxes and tree sidebar (''expected it soon!'').
+{{{
+<?xml version="1.0" encoding="UTF-8" ?>
+
+<!--
+    Boost.LibraryName Sections
+
+    Copyright (c) Year author name, author name
+
+    Distributed under the Boost Software License, Version 1.0.
+    (See accompanying file LICENSE_1_0.txt or copy at
+    http://www.boost.org/LICENSE_1_0.txt)
+                                                                           -->
+
+<nestedLinks version="1.0">
+
+    <title tag="Sections"                     href="index.html" />
+
+    <link tag="Introduction"                  href="library_name/introduction.html" />
+    <link tag="Moderate size section"         href="library_name/moderate_section.html" >
+        <link  tag="First Subsection"         href="library_name/moderate_section/first_subsection.html" />
+        <link  tag="Second Subsection"        href="library_name/moderate_section/second_subsection.html" />
+        <link  tag="Last Subsection"          href="library_name/moderate_section/last_subsection.html" />
+    </link>
+    <link  tag="Larger size section"          href="library_name/larger_section.html" >
+        <link  tag="First Subsection"         href="library_name/larger_section/first_subsection.html" />
+        <link  tag="Second Subsection"        href="library_name/larger_section/second_subsection.html" >
+            <link  tag="Deeper section"       href="library_name/.../deeper_section.html" />
+        </link>
+        <link tag="Last Subsection"           href="library_name/larger_section/last_subsection.html" />
+    </link>
+    <link  tag="Acknowledgments"              href="library_name/acknowledgments.html" />
+
+</nestedLinks>
+}}} 
+
+