wiki:DocsTranslationsProject

Version 25 (modified by Matias Capeletto, 15 years ago) ( diff )

--

http://matias.capeletto.googlepages.com/ibdp.png

Docs Translations

Table of contents

  1. Introduction
  2. Translation Guide
  3. Organization in the repository
  4. Library docs organization example
  5. Volunteers looking for something to do
  6. Volunteers sweating
  7. HTML to Quickbook translations
  8. 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

Docbook source - Required

  • doc/lib_name.xml
    Doc source in docbook format. Optionally it can include boostbook extensions.
    Example: 
    <?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
    Library dependents output configuration parameters (i.e. chunker depth).
    Example: 
    <?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.
    Example: 
    # 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 - Optional

  • doc/lib_name.qbk
    Main quickbook file.
    Example: 
    [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/*.qbk
    Moderate size main sections quickbook files
    Example: 
    [/
    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/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: 
    // 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 >*/
}

//]

    Use it qbk source:
    Example: 
    [/
    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.
    Example: 
    # 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 - 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'').
    Example: 
    <?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.