[[Image(ImprovingBoostDocs:ibdp.png,nolink)]]

   * [ImprovingBoostDocs Improving Boost Docs]
      * [ImprovingBoostDocs About this project]
      * [BoostDocsRepository Boost docs repository]
      * [UnifiedLookAndFeelProject Unified look & feel project]
      * [HelpingBoostAuthors Helping Boost Authors]
      * [GlueDocsProject Glue docs project]
      * [StandardCppLibraryDocumentation Standard C++ Library Docs]
      * [DocumentationBestPractices Documentation Best Practices]
           * '''[DocsOrganization Docs organization proposal]'''
      * [DocumentationTools Documentation Tools]
      * [ImprovingBoostDocsSubprojects Subprojects]
      * [BrowserTestingChart Browser Testing Chart]
      * [LibrariesLogos Logo Playground]

----

= Docs orgainzation proposal =

A standard layout for our docs files.

[[PageOutline(2-4,Table of contents,inline)]]

----

== Docs files Organization ==

'''[#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'').

----

== Docs files examples ==

[[PageOutline(3-4,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
    ;
}}}

[[Br]]

=== 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]
}}}

[[Br]]

=== 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    ]
    ;
}}}

[[Br]]

=== 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>
}}} 


----

   * [ImprovingBoostDocs Improving Boost Docs]
      * [ImprovingBoostDocs About this project]
      * [BoostDocsRepository Boost docs repository]
      * [UnifiedLookAndFeelProject Unified look & feel project]
      * [HelpingBoostAuthors Helping Boost Authors]
      * [GlueDocsProject Glue docs project]
      * [StandardCppLibraryDocumentation Standard C++ Library Docs]
      * [DocumentationBestPractices Documentation Best Practices]
           * '''[DocsOrganization Docs organization proposal]'''
      * [DocumentationTools Documentation Tools]
      * [ImprovingBoostDocsSubprojects Subprojects]
      * [BrowserTestingChart Browser Testing Chart]
      * [LibrariesLogos Logo Playground]