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

Подписка на печатную версию Весь 2015 год (12 номеров) Первое полугодие (6 номеров) Второе полугодие (6 номеров)

Подписка на электронную версию Весь 2015 год (12 номеров) Первое полугодие (6 номеров) Второе полугодие (6 номеров)

Подшивки старых номеров журнала (печатные версии) Весь 2014 год (12 номеров) Первое полугодие (6 номеров) Второе полугодие (6 номеров)

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

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

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

Наш эксперт. Майк Сон­дерс по­тра­тил боль­ше вре­ме­ни на соз­да­ние до­ку­мен­та­ции для сво­ей ОС (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>

В HTML это вы­во­дит­ся в ви­де мо­но­ши­рин­но­го шриф­та. Тэг

<blockquote> 

де­ла­ет от­ступ, а <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), объ­яс­няю­щее ис­поль­зо­вание аб­бре­виа­тур, но­мер вер­сий и дат; кроме того, там со­дер­жа­тся со­ве­ты об­щего характера по на­пи­санию хо­ро­шей до­ку­мен­та­ции. Пренебрегать ими будет себе же во вред.