LXF162:До­ку­мен­та­ция

Версия 02:37, 14 октября 2018

Тек­сто­вые ути­ли­ты. Соз­да­вай­те луч­шие ру­ко­во­дства и ин­ст­рук­ции для сво­их про­ек­тов.

До­ку­мен­та­ция: Всем поможем

Улуч­ши­те жизнь поль­зо­ва­те­лям сво­их про­грамм или чу­жих про­грамм, у ко­то­рых нет хо­ро­ших ру­ко­водств. Майк Сон­дерс по­ка­зы­ва­ет, как это де­ла­ет­ся.

Наш эксперт. Майк Сон­дерс по­тра­тил боль­ше вре­ме­ни на соз­да­ние до­ку­мен­та­ции для сво­ей ОС (http://mikeos.berlios.de), чем на на­пи­са­ние ко­да!

Пи­сать код здо­ро­во – мож­но ори­ги­нальничать, про­бо­вать но­вое, вы­во­дить все из строя и по­хло­пать се­бя по спине, когда что-то по­лу­чит­ся. А вот пи­сать до­ку­мен­та­цию не столь ув­ле­ка­тель­но, осо­бен­но когда вме­сто это­го вы бы луч­ше реа­ли­зо­вы­ва­ли вся­кие функ­ции. Это од­на из при­чин, по ко­то­рой до­ку­мен­та­ция в Linux (не счи­тая по­пу­ляр­ных на­столь­ных при­ло­жений) час­то непол­на. Про­ще го­во­ря, ма­ло ко­му охо­та ее пи­сать.

Од­на­ко хо­ро­шая до­ку­мен­та­ция пре­вра­ща­ет нор­маль­ную про­грам­му в пре­крас­ную. Ва­ша про­грам­ма мо­жет иметь са­мый впе­чат­ляю­щий в ми­ре на­бор функ­ций, а код – ло­пать­ся от гениальней­ших ал­го­рит­мов, но ес­ли никто не в со­стоянии поль­зо­вать­ся ва­шей про­грам­мой или по­нять ва­шу ра­бо­ту, все это на­прас­но.

По­это­му на на­шем уро­ке мы рас­ска­жем об ути­ли­тах и знаниях, необ­хо­ди­мых для соз­дания до­ку­мен­та­ции выс­ше­го ка­че­­ст­ва. Да­же ес­ли вы не про­грам­мист, это все рав­но бу­дет по­лез­но: ре­шив по­мочь ка­ко­му-нибудь про­ек­ту с от­кры­тым ис­ход­ным ко­дом, по­сле чтения этой ста­тьи вы смо­же­те внести свой вклад в ее до­ку­мен­та­цию. Мно­гие про­ек­ты от­ча­ян­но ну­ж­да­ют­ся в хо­ро­ших ав­то­рах для ру­ко­водств, вот мы и на­пра­вим вас на вер­ный путь.

Ис­поль­зо­ва­ние DocBook

Но пре­ж­де чем на­пи­сать хоть сло­во, нуж­но вы­брать фор­мат. Боль­шин­ст­во поль­зо­ва­те­лей ныне ожи­да­ет уви­деть не про­сто тек­сто­вые фай­лы README, а до­ку­мен­та­цию в HTML, PDF или дру­гие роскоши. Тео­ре­ти­че­­ски всю до­ку­мен­та­цию мож­но на­пи­сать в тек­сто­вых фай­лах и за­тем сде­лать вер­сии в HTML и PDF, но это дол­го и тру­до­ем­ко. И ка­ж­дый раз при из­менении тек­сто­вой вер­сии при­дет­ся вно­сить прав­ки в вер­сии и HTML, и PDF.

К сча­стью, ре­шение есть – и это DocBook. Это сис­те­ма генера­ции до­ку­мен­та­ции из од­но­го ис­точника во мно­же­ст­ве фор­ма­тов (HTML, PDF, элек­трон­ные книги, страницы man и мно­гие дру­гие). Ис­точник – это до­ку­мент в фор­ма­те XML, и ра­бо­тать нуж­но толь­ко с ним. На­бор ути­лит пре­об­ра­зу­ет файл XML в дру­гие фор­ма­ты. DocBook весь­ма по­пу­ля­рен в со­об­ще­ст­ве сто­ронников сво­бод­но­го ПО: он при­ме­ня­ет­ся в KDE, Gnome и дру­гих круп­ных про­ек­тах.

Для тех, кто никогда не стал­ки­ва­лся с XML – это фор­мат пред­став­ления дан­ных в тек­сто­вых фай­лах. По су­ти, дан­ные хра­нят­ся в кон­тейнерах, обо­зна­чае­мых сло­ва­ми в уг­ло­вых скоб­ках. Пред­ставь­те се­бе те­ле­фон­ную книгу с абонен­та­ми Бо­бом Сми­том [Bob Smith] и Джо Блог­гзом [Joe Bloggs]. В «обыч­ной», тек­сто­вой вер­сии это бу­дет нечто вро­де

Name: Bob Smith

Number: 01762 271 482

Name: Joe Bloggs

Number: 08293 186 172

Для воспри­ятия че­ло­ве­ком такое хорошо подходит, но оно не слиш­ком стан­дар­ти­зи­ро­ва­но: на­при­мер, в дру­гих те­ле­фон­ных книгах вме­сто двое­то­чий мо­гут ис­поль­зо­вать­ся от­сту­пы и т. д. Без еди­но­го стан­дар­та понадобится множество про­грам­м раз­бор­ки по­доб­ных дан­ных, и каждая будет работать по-своему. Но с по­мо­щью XML мож­но уп­ро­стить ком­пь­ю­те­ру чтение:

<entry>

<name>Bob Smith</name>

<number>01762 271 482</number>

</entry>

<entry>

<name>Joe Bloggs</name>

<number>08293 186 172</number>

</entry>

Те­перь ком­пь­ю­тер пре­крас­но пой­мет, где на­чи­на­ют­ся и за­кан­чи­ва­ют­ся дан­ные. Сло­ва внут­ри уг­ло­вых ско­бок (тэ­ги) не со­дер­жат дан­ных, но иден­ти­фи­ци­ру­ют их. В за­кры­ваю­щем тэ­ге ис­поль­зу­ется пря­мой слэш. Так, тэг <entry> [запись] на­чи­на­ет но­вую запись в те­ле­фон­ной книге, а тэг </entry> за­вер­ша­ет ее (ес­ли вы зна­ко­мы с HTML, то долж­ны по­нять син­так­сис). Дан­ные так­же мож­но вкла­ды­вать друг в дру­га, так что раз­дел <name>…</name> [имя] мо­жет быть внут­ри раз­де­ла <entry>…</entry>, как в на­шем при­ме­ре. Что­бы уп­ро­стить чтение, мож­но вы­де­лять вло­жен­ные раз­де­лы от­сту­пом, но это необя­за­тель­но.

Важ­но от­ме­тить, что XML-фай­лы DocBook фо­ку­си­ру­ют­ся толь­ко на со­дер­жании дан­ных, а не на их пред­став­лении. Тэ­ги опи­сы­ва­ют толь­ко то, ка­кую ин­фор­ма­цию они со­дер­жат – на­звания, па­ра­гра­фы и т. д. – а не то, как ее нуж­но ото­бра­жать или вы­во­дить на пе­чать. Это да­ет нам мак­си­маль­ную гиб­кость для пре­об­ра­зо­вания тек­ста во мно­же­ст­во фор­ма­тов, в чем мы вскорости и убе­дим­ся.

Ути­ли­ты

Фай­лы DocBook мож­но пи­сать в лю­бом тек­сто­вом ре­дак­то­ре, но вам так­же по­на­до­бят­ся про­грам­мы для их кон­вер­та­ции: xsltproc и docbook-xsl. Они есть в боль­шин­ст­ве ди­ст­ри­бу­ти­вов, а для их уста­нов­ки в Ubuntu и дру­гих ди­ст­ри­бу­ти­вах на осно­ве Debian доста­точ­но вы­звать apt-get. От­крой­те свой лю­би­мый тек­сто­вый ре­дак­тор и вве­ди­те сле­дую­щий текст:

<?xml version=”1.0” encoding=”UTF-8”?>

<!DOCTYPE article PUBLIC “-//OASIS//DTD DocBook XML

V4.4//EN” “http://docbook.org/xml/4.4/docbookx.dtd”>

<article>

<title>Как поль­зо­вать­ся про­грам­мой FooProg 1.0</title>

<section>

<title>Вы­зов из ко­манд­ной стро­ки</title>

<para>Да про­сто на­бе­ри­те fooprog!</para>

<para>Все­го и де­лов.</para>

</section>

</article>

Пер­вые две стро­ки по­ка­жут­ся но­вич­кам в XML аб­ра­ка­даб­рой, но они всего-навсего по­яс­ня­ют ин­тер­пре­та­то­ру, что это за до­ку­мент. За­тем мы оп­ре­де­ля­ем ста­тью [article] и ее за­го­ло­вок [title] и соз­да­ем раз­дел [section]. Здесь вы ви­ди­те мно­же­ст­вен­ное вло­жение – раз­дел со­сто­ит из па­ра­гра­фов, а ста­тья – из раз­де­лов.

Те­перь со­храните файл (в фор­ма­те UTF-8) под именем test.xml в до­машнем ка­та­ло­ге, от­крой­те ок­но тер­ми­на­ла и ско­ман­дуй­те

xsltproc -o test.html /usr/share/xml/docbook/stylesheet/nwalsh/xhtml/docbook.xsl test.xml

Итак, те­перь у нас дол­жен поя­вить­ся файл test.html (ес­ли нет, и вы сде­ла­ли ошиб­ку в фай­ле, поя­вит­ся со­об­щение об ошиб­ке с ука­занием на стро­ку). От­крой­те test.html в брау­зе­ре, и вуа­ля – ва­ша до­ку­мен­та­ция в web-фор­ма­те.

Вы ви­ди­те, что ко­ман­да сгенериро­ва­ла да­же со­дер­жание; ес­ли до­ба­вить в до­ку­мент но­вые раз­де­лы (<section>...</section>), ссыл­ки на них поя­вят­ся и в со­дер­жании.

Вве­дение в XSLT

Те­перь по­смот­рим, что имен­но де­ла­ет ко­ман­да. Вы помните, что в фай­лах DocBook нет ника­кой ин­фор­ма­ции о пред­став­лении дан­ных, а в HTML-вер­сии у нас есть боль­шие и ма­лень­кие шриф­ты, го­ри­зон­таль­ная линия и дру­гие эле­мен­ты фор­ма­та. От­ку­да они взя­лись?

От­вет – XSLT (Extensible Stylesheet Language Transformations – пре­об­ра­зо­вания рас­ши­ряе­мо­го язы­ка сти­лей). Это сис­те­ма, по­сред­ст­вом ко­то­рой тэ­ги XML пре­об­ра­зу­ют­ся в нечто иное с до­бав­лением ин­фор­ма­ции о сти­ле. В на­шей ко­ман­де мы вы­зы­ва­ем ‘xsltproc’, про­цес­сор XSLT, с на­шим фай­лом test.xml в ка­че­­ст­ве вход­но­го и test.html в ка­че­­ст­ве вы­ход­но­го (за­да­ет­ся па­ра­мет­ром -o). Но файл, ко­то­рый со­вер­ша­ет все вол­шеб­ст­во – /usr/share/xml/docbook/stylesheet/nwalsh/xhtml/docbook.xsl

За­гля­нув в этот файл, вы ми­гом за­ра­бо­тае­те го­лов­ную боль, по­то­му что там сплошь непо­нят­ный технояз и струк­ту­ры. Доста­точ­но бу­дет ска­зать, что в нем опи­сы­ва­ет­ся, как тэ­ги XML в фай­ле DocBook кон­вер­ти­ру­ют­ся в HTML, и ука­зы­ва­ет­ся необ­хо­ди­мое фор­ма­ти­ро­вание.

Есть и дру­гие таб­ли­цы сти­лей, для кон­вер­та­ции в дру­гие фор­ма­ты. На­при­мер, для пре­об­ра­зо­вания в PDF сна­ча­ла ну­жен про­ме­жу­точ­ный фор­мат XSL-FO (это XML с ин­фор­ма­ци­ей о фор­ма­ти­ро­вании):

xsltproc /usr/share/xml/docbook/stylesheet/docbook-xsl/fo/

docbook.xsl test.xml > test.fo

За­тем нуж­но пре­об­ра­зо­вать test.fo в файл PDF. Это де­ла­ет­ся раз­ны­ми спо­со­ба­ми; один из са­мых про­стых – ути­ли­той fop (в Debian/Ubuntu она уста­нав­ли­ва­ет­ся ко­ман­дой apt-get install fop). За­тем вы­полните ко­ман­ду:

fop test.fo test.pdf

По на­пи­сании до­ку­мен­та­ции вы смо­же­те соз­да­вать скрип­ты (или да­же поль­зо­вать­ся makefile) для генера­ции вер­сий в HTML, PDF и лю­бых дру­гих фор­ма­тах од­ной ко­ман­дой.

На­ря­ду с тэ­га­ми <section>, <title> и <para> есть дру­гие воз­мож­но­сти для струк­ту­ри­за­ции со­дер­жи­мо­го. На­при­мер, вот так соз­да­ют­ся мар­ки­ро­ван­ные спи­ски:

<title>Facts</title>

<itemizedlist>

<listitem><para>Пиво - дело хорошее!</para></listitem>

<listitem><para>Да и винишко тоже.</para></listitem>

<listitem><para>Но Минздрав предупреждает.</para></listitem>

</itemizedlist>

Для ну­ме­ро­ван­но­го спи­ска за­мените itemizedlist на orderedlist. У мно­гих тэ­гов есть ат­ри­бу­ты, ме­няю­щие их по­ве­дение – на­при­мер, по­про­буй­те вме­сто про­сто­го <orderedlist> сле­дую­щий:

<orderedlist numeration=”upperroman”>

Те­перь эле­мен­ты спи­ска бу­дут ну­ме­ро­вать­ся рим­ски­ми циф­ра­ми – и вме­сто 1, 2, 3, 4 вы уви­ди­те I, II, III, IV и т. д. Еще один по­лез­ный ат­ри­бут это­го тэ­га – continuation. Ес­ли уста­но­вить его в continues, то ну­ме­ра­ция бу­дет про­дол­же­на с пре­ды­ду­ще­го спи­ска.

Ат­ри­бу­тов слиш­ком мно­го, что­бы опи­сы­вать их под­роб­но; ес­ли вы хо­ти­те уз­нать про­чие воз­мож­но­сти тэ­га, за­гляните в офи­ци­аль­ную до­ку­мен­та­цию www.docbook.org/tdg51/en/html и най­ди­те раз­дел «DocBook Element Reference».

С тэгом <programlisting> вклю­чаются фраг­мен­ты ко­да:

<programlisting>

10 PRINT INKEY$

20 GOTO 10

</programlisting>

де­ла­ет от­ступ, а <example> вы­во­дит за­го­ло­вок ‘Example [При­мер]’ с но­ме­ром – но­ме­ра генери­ру­ют­ся ав­то­ма­ти­че­­ски, и ес­ли вы до­ба­ви­те но­вый при­мер по­сре­ди до­ку­мен­та­ции, вам не при­дет­ся пе­ре­ну­ме­ро­вы­вать сле­дую­щие. Вы­де­лить раз­дел по­мо­гут тэ­ги <command> или <emphasis>. (В HTML со­дер­жи­мое пер­во­го вы­де­ля­ет­ся жир­ным шриф­том, вто­ро­го – кур­си­вом). Для вклю­чения ссыл­ки на внешний сайт восполь­зуй­тесь тэ­гом <ulink> с па­ра­мет­ром url: <ulink url=”http://www.linuxformat.com”>The best website ever </ulink> Час­то бы­ва­ет нуж­но вклю­чить в до­ку­мен­та­цию внут­ренние ссыл­ки – на дру­гие раз­де­лы. Для это­го восполь­зуй­тесь ат­ри­бу­том id тэ­га <section>, на ко­то­рый за­тем мож­но со­слать­ся. <section id=”compiling”> <title>How to build it</title> ... <para><link linkend=”compiling”>Click here</link> to read the build instructions.</para> Как ви­ди­те, мы за­да­ли иден­ти­фи­ка­тор раз­де­ла (compiling) и за­тем соз­да­ли ссыл­ку на этот раз­дел. Что­бы вста­вить в до­ку­мент изо­бра­жение, восполь­зуй­тесь тэ­га­ми <mediaobject> и <imageobject> сле­дую­щим об­ра­зом: <mediaobject> <imageobject> <imagedata fileref=”austrohungary.png” /> </imageobject> <para>Ав­ст­ро-Венг­рия в 1910 г.</para> </mediaobject> Об­ра­ти­те внимание на за­кры­ваю­щий слеш в тэ­ге <imagedata> – ес­ли внут­ри тэ­га нет ника­ких дан­ных, в конец нуж­но по­ме­щать слэш. Так­же в этом при­ме­ре продемонстрирова­но, как до­бав­ля­ет­ся за­го­ло­вок. В DocBook мно­го дру­гих тэ­гов, но обыч­но они весь­ма спе­ци­фич­ны и не под­хо­дят для об­щей ком­пь­ю­тер­ной до­ку­мен­та­ции. Тэ­гов, ко­то­рые мы изу­чи­ли, вполне доста­точ­но для на­пи­сания ру­ко­водств и спра­вочников для про­ек­тов с от­кры­тым ис­ход­ным ко­дом. Ме­ж­ду вер­сия­ми DocBook 4 и 5 есть неко­то­рые раз­ли­чия; пер­вая до сих пор ши­ро­ко ис­поль­зует­ся и хо­ро­шо до­ку­мен­ти­ро­ва­на в Се­ти – по­это­му здесь мы со­сре­до­то­чи­лись на ней. Но основ­ные знания, ко­то­рые вы по­лу­чи­ли, под­хо­дят к обе­им вер­си­ям.

Пять ша­гов к отличной до­ку­мен­та­ции

Хо­тя в этой ста­тье мы в основ­ном го­во­ри­ли о техниче­­ской сто­роне де­ла, всегда сто­ит помнить и о че­ло­ве­че­­ской сто­роне, т. е. о том, как сде­лать ва­ши ру­ко­во­дства мак­си­маль­но доступ­ны­ми.

1 Ду­май­те как поль­зо­ва­тель

Пред­ставь­те, что вы ви­ди­те про­грам­му (или фраг­мент ко­да) впер­вые. Ка­кие во­про­сы вы за­да­ди­те? Ка­кие за­да­чи вы бу­де­те ре­шать пре­ж­де все­го? Ка­кие эле­мен­ты ин­тер­фей­са мо­гут ока­зать­ся непо­нят­ны­ми?

Важ­но быть осто­рож­ным и не за­кла­ды­вать­ся на пре­ды­ду­щий опыт поль­зо­ва­те­ля. Да­же ес­ли это обыч­ная про­грам­ма – тек­сто­вый про­цес­сор или поч­то­вый кли­ент – по­ду­май­те о том, что поль­зо­ва­тель мог уста­но­вить Linux все­го несколь­ко ча­сов на­зад.

2 Струк­ту­ра пре­ж­де все­го

Ста­рай­тесь мак­си­маль­но раз­би­вать ин­фор­ма­цию на от­дель­ные фраг­мен­ты, ко­то­рые не долж­ны быть слиш­ком боль­ши­ми. На­при­мер, в на­шем жур­на­ле есть раз­де­лы, за­го­лов­ки, врез­ки и дру­гие воз­мож­но­сти, ко­то­рые по­мо­га­ют да­вать ин­фор­ма­цию не в од­ном боль­шом куске тек­ста.

3 Не до­ку­мен­ти­руй­те все

Бы­ли вре­ме­на (осо­бен­но в ми­ре Windows), когда ма­лень­кие зна­ки во­про­са бы­ли раз­бро­са­ны по всем ок­нам, что­бы вы мог­ли по­нять, что де­ла­ет ка­ж­дая кноп­ка. Но вполне оче­вид­но, что кноп­ка «За­крыть» за­кры­ва­ет диа­ло­го­вое ок­но. По­это­му со­сре­до­точь­тесь на основ­ных воз­мож­но­стях и клю­че­вых ас­пек­тах – нет ну­ж­ды пи­сать пять аб­за­цев тек­ста о том, что де­ла­ет кноп­ка «Со­хранить».

4 Бе­се­дуй­те с раз­ра­бот­чи­ка­ми

Ес­ли вы до­ку­мен­ти­руе­те чу­жую про­грам­му, под­дер­жи­вай­те ре­гу­ляр­ную связь с раз­ра­бот­чи­ка­ми, осо­бен­но с те­ми, что от­ве­ча­ют за ин­тер­фейс. Най­дя что-нибудь слиш­ком стран­ное на вид, что­бы быть за­до­ку­мен­ти­ро­ван­ным, или то, что мож­но су­ще­ст­вен­но уп­ро­стить, обя­за­тель­но дай­те знать раз­ра­бот­чи­кам. Ваш со­вет мо­жет иметь для них боль­шое зна­чение.

5 Най­ди­те под­опыт­но­го кро­ли­ка

По воз­мож­но­сти най­ди­те ко­го-то, кто никогда не поль­зо­вал­ся про­грам­мой, дай­те ему све­же­на­пи­сан­ную до­ку­мен­та­цию и смот­ри­те, как он бу­дет ра­бо­тать с про­грам­мой. Это пре­крас­ный спо­соб най­ти недо­че­ты в до­ку­мен­та­ции – или воз­на­гра­дить вас тем, как хо­ро­шо она по­мо­га­ет поль­зо­ва­те­лю!

На­пи­са­ние man-стра­ниц

Со­глас­но пра­ви­лам Debian GNU/Linux, у ка­ж­дой про­грам­мы долж­на быть man-страница. Сколь­ко раз вам в ка­та­ло­ге /usr/bin по­па­да­лась про­грам­ма со стран­ным именем, и вы не пред­став­ля­ли, что она де­ла­ет? Да­же про­стей­шая man-страница с пя­ти­строч­ным опи­санием про­грам­мы все из­менит.

Для гра­фи­че­­ской про­грам­мы, функ­цио­наль­ность ко­то­рой про­яв­ля­ет­ся внут­ри про­грам­мы, а не че­рез па­ра­мет­ры команд­ной стро­ки, под­роб­ная man-страница не нуж­на. Но для ути­лит команд­ной стро­ки хо­ро­шая до­ку­мен­та­ция име­ет ре­шаю­щее зна­чение. Для досту­па к man-страницам ис­поль­зу­ет­ся од­но­имен­ная ко­ман­да – на­при­мер, man ls. Эти страницы пи­шут­ся не про­стым тек­стом, а осо­бым язы­ком раз­мет­ки с до­полнитель­ным фор­ма­ти­ро­ванием. Про­смот­реть страницу с раз­мет­кой мож­но, на­при­мер, так:

zless /usr/share/man/man1/ls.1.gz

Ес­ли вы хо­ти­те по­ра­бо­тать с тек­сто­вы­ми фай­ла­ми, мо­же­те взять неболь­шую страницу из это­го ка­та­ло­га (на­при­мер, znew.1.gz), ско­пи­ро­вать ее в свой до­машний ка­та­лог, рас­па­ко­вать ее ко­ман­дой gunzip и по­ра­бо­тать с ней. Что­бы про­смот­реть ее про­грам­мой man, ука­жи­те путь и имя фай­ла:

man ./znew.1

(На­брав про­сто man znew, вы уви­ди­те вер­сию из /usr/share/man/man1.) Рас­смот­рим не­сколь­ко пер­вых строк это­го фай­ла:

.TH ZNEW 1

.SH NAME

znew \- пре­об­ра­зу­ет фай­лы .Z в фай­лы .gz

.SH SYNOPSIS

.B znew

[ -ftv9PK] [ name.Z ... ]

.SH DESCRIPTION

.I Znew

пре­об­ра­зу­ет фай­лы из фор­ма­та .Z (compress) в фор­ма­та .gz (gzip).

Ес­ли вы хо­ти­те зан­ово сжать файл в фор­ма­те gzip, пе­ре­име­нуй­те файл:

что­бы он по­лу­чил рас­ши­ре­ние .Z, за­тем при­ме­ни­те znew.

.SH OPTIONS

.TP

.B \-f

Пре­об­ра­зо­вание из фор­ма­та .Z в фор­мат .gz, да­же ес­ли файл .gz уже су­ще­ст­ву­ет.

• Метамодернизм в позднем творчестве В.Г. Сорокина
• ЛитРПГ - последняя отрыжка постмодерна
• "Ричард III и семиотика"
• 3D-визуализация обложки Ridero создаем обложку книги при работе над самиздатом.
• Архитектура метамодерна - говоря о современном искусстве, невозможно не поговорить об архитектуре. В данной статье будет отмечено несколько интересных принципов, характерных для построек "новой волны", столь притягательных и скандальных.
• Литература
• Метамодерн
• Рокер-Прометей против изначального зла в «Песне про советскую милицию» Вени Дркина, Автор: Нина Ищенко, к.ф.н, член Союза Писателей ЛНР - перепубликация из журнала "Топос".
• Как избавиться от комаров? Лучшие типы ловушек.
• Что делать если роблокс вылетает на windows
• Что делать, если ребенок смотрит порно?
• Почему собака прыгает на людей при встрече?
• Какое масло лить в Задний дифференциал (мост) Visco diff 38434AA050
• О чем может рассказать хвост вашей кошки?
• Верветки
• Отчетность бюджетных учреждений при закупках по Закону № 223-ФЗ
• Срок исковой давности как правильно рассчитать
• Дмитрий Патрушев минсельхоз будет ли преемником Путина
• Кто такой Владислав Поздняков? Что такое "Мужское Государство" и почему его признали экстремистским в России?
• Как правильно выбрать машинное масло в Димитровграде?
• Как стать богатым и знаменитым в России?
• Почему фильм "Пипец" (Kick-Ass) стал популярен по всему миру?
• Как стать мудрецом?
• Как правильно установить FreeBSD
• Как стать таким как Путин?
• Где лучше жить - в Димитровграде или в Ульяновске?
• Почему город Димитровград так называется?
• Что такое метамодерн?
• ВАЖНО! Временное ограничение движения автотранспортных средств в Димитровграде
• Тарифы на электроэнергию для майнеров предложено повысить

В язы­ке раз­мет­ки man-страниц ко­ман­ды фор­ма­ти­ро­вания на­чи­на­ют­ся с точ­ки. Итак, пря­мо в пер­вой стро­ке мы ви­дим .TH, что оз­на­ча­ет «за­го­ло­вок страницы [title header]». За ним сле­ду­ют имя про­грам­мы и род man-страниц, к ко­то­рой она при­над­ле­жит (1 для поль­зо­ва­тель­ских команд, 5 для кон­фи­гу­ра­ци­он­ных фай­лов и 8 для ути­лит сис­тем­но­го ад­минист­ри­ро­вания). Здесь так­же мож­но ука­зать да­ту в ка­выч­ках, на­при­мер, “23 September 2012”, и она поя­вит­ся в верхней час­ти man-страницы. За­тем сле­ду­ет .SH, за­го­ло­вок раз­де­ла [section header]. Он вы­во­дит­ся жир­ным шриф­том, вы­ровнен­ным по ле­во­му краю ок­на, обыч­но за­глав­ны­ми бу­каа­ми. Пол­ная, хо­ро­шо написан­ная страница man долж­на иметь сле­дую­щие раз­де­лы:

» NAME Опи­сание в од­ну стро­ку

» SYNOPSIS Па­ра­мет­ры ко­ман­ды

» DESCRIPTION Крат­кое по­яснение ра­бо­ты про­грам­мы

» OPTIONS Под­роб­ное опи­сание па­ра­мет­ров

» EXAMPLES При­ме­ры ре­шения раз­лич­ных за­дач (обя­за­те­лен, ес­ли у про­грам­мы мно­го па­ра­мет­ров)

» BUGS Лю­бое необыч­ное по­ве­дение про­грам­мы

» AUTHOR Ваш элек­трон­ный ад­рес и/или ссыл­ка на сайт

Оп­ции .B и .I вы­де­ля­ют текст жир­ным шриф­том и кур­си­вом со­от­вет­ст­вен­но. На обыч­ных тер­ми­на­лах Unix кур­сив не ото­бра­жа­ет­ся, по­это­му текст с оп­ци­ей .I мо­жет под­чер­ки­вать­ся или вы­де­лять­ся дру­гим цве­том. Вы ви­ди­те, что .TP на­чи­на­ет но­вый аз­бац с от­сту­пом для всех строк, кро­ме пер­вой. Ти­ре луч­ше пред­ва­рять об­рат­ным слэ­шем (\-), ина­че про­цес­сор мо­жет ин­тер­пре­ти­ро­вать их как де­фи­сы.

Ес­ли кому по ду­ше гра­фи­че­­ские про­грам­мы, здесь вам круп­но не по­вез­ло. Про­грам­ма ManEdit непло­хо справ­ля­лась с этой за­да­чей, но она дол­го не об­нов­ля­лась, и ее слож­но за­ста­вить ра­бо­тать в при­лич­ных ди­ст­ри­бу­ти­вах (она осно­ва­на на GTK 1). В Gmanedit есть по­ша­го­вый мас­тер соз­дания но­вой man-страницы, но вам все рав­но при­дет­ся ра­бо­тать с раз­ме­чен­ным тек­стом. |

Работа с документами KDE и Gnome

Оба глав­ных ра­бо­чих сто­ла ис­поль­зу­ют для до­ку­мен­та­ции DocBook, и обо­им про­ек­там всегда нуж­ны но­вые по­мощники. Са­мый про­стой спо­соб по­мочь – за­пустить свои лю­би­мые про­грам­мы Gnome/KDE, от­крыть ок­но справ­ки и по­смот­реть, че­го не хва­та­ет. Не­ко­то­рые про­грам­мы уже име­ют об­шир­ную до­ку­мен­та­цию, но ее все рав­но мож­но улуч­шить – на­при­мер, она мо­жет быть неак­ту­аль­ной или в ней мо­жет недоста­вать раз­де­ла. Най­дя функ­цию, ко­то­рую труд­но по­нять, за­гляните в справ­ку, и ес­ли она недоста­точ­но хо­ро­шо опи­са­на, вы мо­же­те это улуч­шить. Важ­ный со­вет: ес­ли вы най­де­те про­грам­му без до­ку­мен­та­ции (или с очень пло­хой до­ку­мен­та­ци­ей), не хватай­тесь за де­ло сра­зу и не пи­ши­те сотни слов. Сна­ча­ла свя­жи­тесь с раз­ра­бот­чи­ка­ми или най­ди­те IRC-ка­нал про­ек­та и уз­най­те, не ра­бо­та­ет ли над до­ку­мен­та­ци­ей кто-то еще.

Бу­дет до­сад­но, ес­ли вы по­тра­ти­те несколь­ко недель на боль­шой фраг­мент тек­ста и ока­жет­ся, что готовое описание уже есть!

В Gnome имеется удоб­ное ру­ко­во­дство для но­вых ав­то­ров – http://developer.gnome.org/gdp-handbook/stable/gettingstarted.html.en, эк­ви­ва­лент для KDE – http://community.kde.org/Getinvolved/documentation.

На ка­ж­дой из этих страниц вы най­де­те ссыл­ки на дру­гие ру­ко­во­дства, которые объ­яс­няют прие­мы и со­гла­шения, принятые про­ек­тами. На­при­мер, для KDE су­ще­ст­ву­ет ру­ко­во­дство по сти­лям (http://l10n.kde.org/docs/styleguide/index.html), объ­яс­няю­щее ис­поль­зо­вание аб­бре­виа­тур, но­мер вер­сий и дат; кроме того, там со­дер­жа­тся со­ве­ты об­щего характера по на­пи­санию хо­ро­шей до­ку­мен­та­ции. Пренебрегать ими будет себе же во вред.