|
Documenting libraries
BoostBook является расширением DocBook, форматом XML для представления документации. BoostBook наследует большую часть своей функциональности и многие элементы из DocBook, которые не переизданы здесь. При написании документации BoostBook, пожалуйста, обратитесь также к DocBook: The Definitive Guide.
Defining a BoostBook libraryБиблиотечная документация BoostBook полностью содержится в элементе XML. Для создания скелетной библиотеки нам необходимо создать новый XML-документ (назовите его any.xml), который содержит основную информацию о библиотеке. Следующий пример BoostBook XML описывает основную информацию о Boost. Любая библиотека:
Example 44.1. A Skeletal BoostBook Library
<?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 name="Any" dirname="any" xmlns:xi="http://www.w3.org/2001/XInclude"
id="any" last-revision="$Date$">
<libraryinfo>
<author>
<firstname>Kevlin</firstname>
<surname>Henney</surname>
</author>
<librarypurpose>
Safe, generic container for single values of different value types
</librarypurpose>
<librarycategory name="category:data-structures"/>
</libraryinfo>
</library>
Первые три строки идентифицируют этот документ как документ BoostBook XML. Линия DOCTYPE гласит, что документ соответствует BoostBook DTD, и что элемент верхнего уровня является BoostBook .
Элемент фактически описывает аспекты библиотечной документации BoostBook. Атрибуты элемента :
Attributes for the <library> element
name- The full name of the library, e.g., "Any"
dirname- The name of the directory, relative to
boost/libs, in which the library
resides. This name may be a relative path, such as
math/octonion, using "/" for the directory
separator.
id- A short, unique name for the library. For libraries
with simple directory names (e.g., ones that do not contain
a "/"), this should be the same as the
dirname. This id will be used to
identify libraries and, for HTML output, will be used as the
base name for the HTML file in which the library's
documentation resides, so it should use only lowercase
alphanumeric characters and underscores.
last-revision- Always set to
$Date$, which is
expanded by CVS to include the date and time that the file
was last modified.
Внутри элемента мы имеем элемент , который дает информацию о самой библиотеке. Оно содержит имя автора (может быть более одного элемента ), за которым следует цель библиотеки и список категоризации. Элемент всегда должен содержать очень короткое (однозначное) описание цели библиотеки и должен не заканчиваться периодом.
Список категорий определяется набором элементов . Каждый элемент имеет элемент имя, который идентифицирует одну из категорий. Фактический список категорий находится в файле doc/src/boost.xml.
На данный момент мы можем применить таблицы стилей BoostBook XSL к any.xml (до DocBook), за которым следует таблица стилей DocBook XSL для создания HTML-выхода, как описано в разделе под названием “Getting Started”.
Большинство авторов библиотеки довольны написанием документации HTML. Написание DocBook документация (и, в дополнение, документация BoostBook) очень похожа на на написание HTML, за исключением того, что BoostBook использует разные названия элементов из HTML (см. Table 44.2, “Converting HTML-элементы для BoostBook”) и BoostBook XML - гораздо более жесткий формат, чем HTML.
Один из самых простых способов конвертировать HTML-документацию в документацию BoostBook - использовать HTML Tidy для преобразования вашего HTML в действительный XHTML, который позволит убедиться, что все элементы должным образом закрыты, а затем применить преобразования в Table 44.2, “ Переключение HTML-элементов в BoostBook” в корпус документа XHTML. Следующая команда использует HTML Tidy для преобразования HTML в действительный XHTML:
tidy -asxhtml input.html > output.xhtml
При преобразовании документации из HTML в BoostBook обратите внимание, что некоторая избыточная информация, которая должна быть сохранена вручную в HTML, автоматически генерируется в BoostBook: например, библиотечные категоризации, цель и список авторов, описанный в разделе под названием “ Определение библиотеки BoostBook” используются как в документации для библиотеки, так и для создания алфавитных и категоризированных списков известных библиотек; аналогично, таблицы содержимого строятся автоматически из названий разделов в документе BoostBook.
Table 44.2. Converting HTML elements to BoostBook
| HTML |
BoostBook |
, и т.д. |
, ; See <a class="xref" href="?tid=11741#boostbook.sectioning" title="Sectioning in BoostBook">the section called “Sectioning in BoostBook”</a><!-- [TR_END] --><!-- [ORIG_BEGIN]<section>, <title>; See <a class="xref" href="?tid=11741#boostbook.sectioning" title="Sectioning in BoostBook">the section called “Sectioning in BoostBook”</a>[ORIG_END] --></p>
</td>
</tr>
<tr>
<td align="left"><p><!--[TR_BEGIN]--><i>, <em><!-- [TR_END] --><!-- [ORIG_BEGIN]<i>, <em>[ORIG_END] --></p></td>
<td align="left"><p><!--[TR_BEGIN]--><emphasis ><!-- [TR_END] --><!-- [ORIG_BEGIN]<emphasis>[ORIG_END] --></p></td>
</tr>
<tr>
<td align="left"><p><!--[TR_BEGIN]--><b><!-- [TR_END] --><!-- [ORIG_BEGIN]<b>[ORIG_END] --></p></td>
<td align="left"><p><!--[TR_BEGIN]--><emphasis role="bold"><!-- [TR_END] --><!-- [ORIG_BEGIN]<emphasis role="bold">[ORIG_END] --></p></td>
</tr>
<tr>
<td align="left"><p><!--[TR_BEGIN]--><ol><!-- [TR_END] --><!-- [ORIG_BEGIN]<ol>[ORIG_END] --></p></td>
<td align="left"><p><!--[TR_BEGIN]--><orderedlist ><!-- [TR_END] --><!-- [ORIG_BEGIN]<orderedlist>[ORIG_END] --></p></td>
</tr>
<tr>
<td align="left"><p><!--[TR_BEGIN]--><ul><!-- [TR_END] --><!-- [ORIG_BEGIN]<ul>[ORIG_END] --></p></td>
<td align="left"><p><!--[TR_BEGIN]--><itemizedlist ><!-- [TR_END] --><!-- [ORIG_BEGIN]<itemizedlist>[ORIG_END] --></p></td>
</tr>
<tr>
<td align="left"><p><!--[TR_BEGIN]--><li><!-- [TR_END] --><!-- [ORIG_BEGIN]<li>[ORIG_END] --></p></td>
<td align="left"><p><!--[TR_BEGIN]--><listitem ><!-- [TR_END] --><!-- [ORIG_BEGIN]<listitem>[ORIG_END] --></p></td>
</tr>
<tr>
<td align="left"><p><!--[TR_BEGIN]--><pre><!-- [TR_END] --><!-- [ORIG_BEGIN]<pre>[ORIG_END] --></p></td>
<td align="left"><p><!--[TR_BEGIN]--><programlisting><!-- [TR_END] --><!-- [ORIG_BEGIN]<programlisting>[ORIG_END] --></p></td>
</tr>
<tr>
<td align="left"><p><!--[TR_BEGIN]--><code><!-- [TR_END] --><!-- [ORIG_BEGIN]<code>[ORIG_END] --></p></td>
<td align="left"><p><!--[TR_BEGIN]--><computeroutput>,<code><!-- [TR_END] --><!-- [ORIG_BEGIN]<computeroutput>,<code>[ORIG_END] --></p></td>
</tr>
<tr>
<td align="left"><p><!--[TR_BEGIN]--><p><!-- [TR_END] --><!-- [ORIG_BEGIN]<p>[ORIG_END] --></p></td>
<td align="left"><p><!--[TR_BEGIN]--><para>, <simpara><!-- [TR_END] --><!-- [ORIG_BEGIN]<para>, <simpara>[ORIG_END] --></p></td>
</tr>
<tr>
<td align="left"><p><!--[TR_BEGIN]--><a><!-- [TR_END] --><!-- [ORIG_BEGIN]<a>[ORIG_END] --></p></td>
<td align="left">
<p><!--[TR_BEGIN]--><xref>, <link>, <ulink>;, See <a class="xref" href="?tid=11742#boostbook.linking" title="Linking in BoostBook">the section called “Linking in BoostBook”</a><!-- [TR_END] --><!-- [ORIG_BEGIN]<xref>, <link>, <ulink>;, See <a class="xref" href="?tid=11742#boostbook.linking" title="Linking in BoostBook">the section called “Linking in BoostBook”</a>[ORIG_END] --></p>
</td>
</tr>
<tr>
<td align="left"><p><!--[TR_BEGIN]--><table>, <tr>, <th>, <td><!-- [TR_END] --><!-- [ORIG_BEGIN]<table>, <tr>, <th>, <td>[ORIG_END] --></p></td>
<td align="left"><p><!--[TR_BEGIN]--><table>, <informaltable>, <tgroup>, <thead>, <tfoot>, <tbody>, <row>, <entry>, <entrytbl> Столы BoostBook эквивалентны таблицам DocBook, для которых здесь есть хороший <a href="http://opensource.bureau-cornavin.com/crash-course/en/tables.html" target="_top">tutorial</a><!-- [TR_END] --><!-- [ORIG_BEGIN]<table>, <informaltable>, <tgroup>, <thead>, <tfoot>, <tbody>, <row>, <entry>, <entrytbl>; BoostBook tables are equivalent to DocBook tables, for which there is a good <a href="http://opensource.bureau-cornavin.com/crash-course/en/tables.html" target="_top">tutorial here</a>[ORIG_END] --></p></td>
</tr>
</tbody>
</table></div>
</div>
<br class="table-break">
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="boostbook.sectioning"></a>Sectioning in BoostBook</h3></div></div></div>
<p><!--[TR_BEGIN]-->«Раздел» означает организацию документа на отдельные разделы, каждый с названием, некоторым текстом и, возможно, подразделами. Каждый раздел описан в BoostBook через элемент <section>. Раздел введения может выглядеть так:<!-- [TR_END] --><!-- [ORIG_BEGIN]"Sectioning" refers to organization of a document into separate sections, each with a title, some text, and possibly subsections. Each section is described in BoostBook via a <section> element. An introduction section may look like this:[ORIG_END] --></p>
<pre class="programlisting">
<section id="any.intro">
<title>Introduction</title>
<para>Introduction to a library...</para>
<section>
<title>A Subsection</title>
<para>Subsection information...</para>
</section>
</section>
</pre>
<p><!--[TR_BEGIN]-->Элемент <section> содержит всю информацию, которая логически должна быть сгруппирована в этом разделе. Название раздела помещается в элемент <title> и любые пункты, программы, списки, таблицы или подразделы могут происходить в разделе. атрибут <code class="computeroutput">id</code> элемента <section> дает уникальный идентификатор для каждого раздела, чтобы впоследствии его можно было идентифицировать для подключения. Предполагается, что все идентификаторы начинаются с короткого названия библиотеки, за которым следует период, так что идентификаторы не конфликтуют между библиотеками.<!-- [TR_END] --><!-- [ORIG_BEGIN]The <section> element contains all information that
should logically be grouped within that section. The title of the
section is placed within the <title> element, and any
paragraphs, programs, lists, tables, or subsections can occur
within the section. The <code class="computeroutput">id</code> attribute of the
<section> element gives a unique ID to each section, so that
it may later be identified for linking. It is suggested that all
IDs start with the short name of a library followed by a period,
so that IDs do not conflict between libraries.[ORIG_END] --></p>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2003-2005 Douglas Gregor<p><!--[TR_BEGIN]-->Distributed under the Boost Software License, Version 1.0. (См. сопроводительный файл LICENSE_1_0.txt или копия на <a href="https://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>).<!-- [TR_END] --><!-- [ORIG_BEGIN]Distributed under the Boost Software License, Version 1.0.
(See accompanying file LICENSE_1_0.txt or copy at
<a href="https://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>).
[ORIG_END] --></p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="?tid=11740"><img src="/img/prev.png" alt="Prev"></a><a accesskey="u" href="?tid=4886"><img src="/img/up.png" alt="Up"></a><a accesskey="h" href="?tid=241"><img src="/img/home.png" alt="Home"></a><a accesskey="n" href="?tid=11742"><img src="/img/next.png" alt="Next"></a>
</div>
<p>Статья <strong>Documenting libraries</strong> раздела The Boost C++ Libraries BoostBook Documentation Subset <a href = "/?did=4886">Chapter 44. The BoostBook Documentation Format</a> может быть полезна для разработчиков на c++ и boost.</p><noindex><br><br><br><p class="copyrighttext">Материалы статей собраны из открытых источников, владелец сайта не претендует на авторство. Там где авторство установить не удалось, материал подаётся без имени автора. В случае если Вы считаете, что Ваши права нарушены, пожалуйста, свяжитесь с владельцем сайта.</p><br>
</noindex><hr><p align="center">:: <a href="/">Главная</a> :: <a href = "/?did=4886">Chapter 44. The BoostBook Documentation Format</a> :: </p><hr><table class="orangetable" width="99%" border="0" cellpadding="4" cellspacing="2"><tr><td class="orangeheader"><p class="smalltext">реклама</p></td></tr>
<tr><td class="copyrighttext">
<!-- SAPE RTB DIV 600x340 -->
<div id="SRTB_907055"></div>
<!-- SAPE RTB END -->
</td></tr></table>
<hr>
<div align="center">
<form action="/index.php?do=find" method="post" enctype="application/x-www-form-urlencoded" name="form1">
<input name="find" type="text" id="find" size="45">
<input type="submit" name="Submit" value="Поиск по сайту">
</form>
</div>
</td>
<td width="20">
</td></tr>
<tr><td Height="13" colspan="3" class="copyrighttext"><div align="center"> ©KANSoftWare (<em><a href="https://www.kansoftware.ru/">разработка программного обеспечения</a>, <a href="https://www.kansoftware.ru/">создание программ</a>, <a href="https://www.kansoftware.ru/">создание интерактивных сайтов</a></em>), 2007<br>
<noindex>
<!-- Top.Mail.Ru counter -->
<script type="text/javascript">
var _tmr = window._tmr || (window._tmr = []);
_tmr.push({id: "662961", type: "pageView", start: (new Date()).getTime()});
(function (d, w, id) {
if (d.getElementById(id)) return;
var ts = d.createElement("script"); ts.type = "text/javascript"; ts.async = true; ts.id = id;
ts.src = "https://top-fwz1.mail.ru/js/code.js";
var f = function () {var s = d.getElementsByTagName("script")[0]; s.parentNode.insertBefore(ts, s);};
if (w.opera == "[object Opera]") { d.addEventListener("DOMContentLoaded", f, false); } else { f(); }
})(document, window, "tmr-code");
</script>
<noscript><div><img src="https://top-fwz1.mail.ru/counter?id=662961;js=na" style="position:absolute;left:-9999px;" alt="Top.Mail.Ru" /></div></noscript>
<!-- /Top.Mail.Ru counter -->
<!-- Top.Mail.Ru logo -->
<a href="https://top-fwz1.mail.ru/jump?from=662961">
<img src="https://top-fwz1.mail.ru/counter?id=662961;t=472;l=1" height="31" width="88" alt="Top.Mail.Ru" style="border:0;" /></a>
<!-- /Top.Mail.Ru logo -->
</noindex>
</div></td><td>
</td></tr>
</table>
</body>
</html>
<p>Время компиляции файла: 2024-08-30 11:47:00<br>2025-05-19 23:42:53/0.0095798969268799/1</p> | |
