| Version 34 (modified by , 15 years ago) ( diff ) |
|---|
Docs Translations
Table of contents
- Introduction
- Translation Guide
- Organization in the repository
- Library docs organization example
- Volunteers looking for something to do
- Volunteers sweating
- HTML to Quickbook translations
- Boostbook to Quickbook translations
Introduction
The translated docs will be located in: SVN: snadbox/boost_docs/trunk/libs/lib_name/doc
Once they are stable, the lib author will be invited to see the results and commit them to the correct location CVS: boost/libs/lib_name/doc
Translation Guide
To translate html docs we should wait for the result of Glyn Matthews's Html to docbook project.
Once we have docbook docs, if the authors wants to have a Quickbook version of it (really recommended), we can use the "Quickbook source" stylesheet. It works very well in Opera ( Menu: "View" ---> "Style" ---> "Quickbook source" ).
Organization in the repository
SVN: snadbox/boost_docs/trunk/libs/lib_name
Docbook source - Required
- doc/lib_name.xml
Doc source in docbook format. Optionally it can include boostbook extensions. - doc/lib_name.xsl
Library dependents output configuration parameters (i.e. chunker depth). - doc/Jamfile.v2
"doc/bjam --v2" will generate the html docs.
Quickbook Source - Optional
- doc/lib_name.qbk
Main quickbook file.
- doc/*.qbk
Moderate size main sections quickbook files
- doc/larger_section.qbk
- doc/larger_section/*.qbk
Large size main sections (i.e reference) may be splitted again, organizing them in a directory tree to avoid clutering the doc directory.
Images - Optional
- doc/images/*.png
You can use other formats, but be a good web citizen and use portable networks graphics. - doc/images/*.svg
If you intend to have a decent rendering in the pdf docs, use svg.
Examples - Optional
- example/doc/*.cpp
Quickbook allows us to import code chuncks, instead of harcoding 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/Jamfile.v2
Testsuite for the doc examples.
Navigation aid - Will be automated in the future
- doc/html/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).
Library docs organization example
Examples list
[Docbook source
doc/lib_name.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"><</phrase><phrase role="identifier">iostream</phrase><phrase role="special">></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"><<</phrase> <phrase role="string">"Hello, World\n"</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
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
"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
doc/lib_name.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
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 Highligthing ][Both in code blocks and in `inline code` ]]
]
[endsect]
Doc Examples
example/doc/code_example.cpp
Quickbook allows us to import code chuncks, instead of harcoding 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
[/
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
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
doc/html/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>
Volunteers looking for something to do
Add yourself here!
Volunteers sweating
- Stjepan Rajko (translating smart_ptr)
- Glyn Matthews (translating bind and mem_fun)
- Darren Garvey (lists.drrngrvy@… : translating tribool and range)
- Andrew Sutton (translating and improving graph docs)
- Matias Capeletto (translating boostbook to quickbook)
HTML to Quickbook translations
Finished work
- optional (Matias Capeletto)
- numeric_conversion (Matias Capeletto)
- config (Matias Capeletto)
Ongoing
- smart_ptr (assigned to Stjepan Rajko)
- bind (assigned to Glyn Matthews)
- mem_fun (assigned to Glyn Matthews)
- graph (assigned to Andrew Sutton)
Pending
- wave (translator wanted)
- serialization (translators wanted... it may be too big for one person)
- spirit (translators wanted)
Authozarization from author needed
- compatibility
- crc
- dynamic_bitset
- integer
- pool
- random
- rational
- timer
- tokenizer
Boostbook to Quickbook translations
- tribool (assigned to Darren Garvey)
- range (assigned to Darren Garvey)
This translations are low priority for now.
- string_algo (translator wanted)
- function (translator wanted)
- signals (translator wanted)
- assign (translator wanted)
- ptr_container (translator wanted)
Note:
See TracWiki
for help on using the wiki.
