[docs] Re: новый ALT Docs HOWTO: черновик раздела

Пн Авг 9 16:53:26 MSD 2004

Привет!

Спасибо за развернутые и дельные комментарии к черновику. 
Я на некоторые из них хотел бы ответить, с остальными согласен, 
поэтому просто их пропущу. Но прежде частных комментариев 
хотелось бы сделать резюме: 

Насколько я понял, Ваша общая идея примерно в том, что важнее 
найти инструмент, с помощью которого можно было бы писать текст
с нужной разметкой, чем объяснять и указывать автору, как и что 
нужно размечать. Я совершенно согласен с тем, что инструмент нужен
и готов включаться в его поиски/разработку, но тем не менее
я глубоко уверен, что указания и объяснения автору нужны даже 
больше. Потому что никакая программа не укажет человеку, что 
имена файлов и примеры команд нужно выделить специальным тегом, 
для списков использовать специальные элементы, а не просто цифры и т. д., 
короче говоря, не заставит его делать правильную логическую разметку.
Я специально привожу крайние примеры, для наглядности. 

Так что я думаю, что в Docs HOWTO мой раздел (исправленный по 
Вашим замечаниям) включить все-таки нужно. И нужно договориться
об этом сейчас, потому что я очень хочу собрать для 
Master 2.4 пакет с документацией разработчику ALT, и Docs HOWTO 
тоже должно туда войти в максимально обновлённой форме.

Ниже кое на что отвечу, с чем не согласен.

> >Правила разметки документации ALT Linux
> >
> >что он позволяет производить смысловую разметку документа, 
> >не ориентированную непосредственно на тот или иной конечный 
> >формат электронной или печатной публикации. Однако 
> >DOCBOOK XML -- это очень обширная спецификация, включающая 
> >около 400 понятий. Поэтому у автора или редактора документации 
> 
> Здесь Вы называниете понятием теги, а далее в тексте - сущности. 
> Если придерживаться устоявшихся терминов, будет меньше путанницы.
Согласен, разнобой уберу, но перевод "сущность" мне не нравится 
страшно: он и неказистый, и вызывает неправильные ассоциации. 
Перевод entity как "понятие" гораздо более удачен, поэтому 
я и придерживался его, указывая в скобках (entity). 

> >времени, которым редко располагает разработчик, документирующий 
> >программу. И во-вторых, при разметке документа в DOCBOOK возникают 
> >трудности с тем, какой из многочисленных доступных элементов 
> >следует выбрать для разметки той или иной части документа. 
> 
> Кстати, обе эти проблемы решаются использованием редактора, 
> понимающего допустимые в контексте теги, и показывающего 
> соответствущий html для тега из DocBook TDG.
Проблема выбора тега не решается формальной допустимостью в контексте, 
нужно еще ведь и объяснить пользователю, какой по смыслу тег ему нужен.
Автоматический подбор тега по смыслу невозможен.

> >сравнительно небольшого подмножества DOCBOOK позволяет 
> >и быстро освоить разметку, и избежать разнобоя и при этом 
> >сохранить все преимущества технологии DOCBOOK.
> 
> Уже есть такое подмножество в рамках того же DocBook TC, там 106 
> тегов:
> http://www.oasis-open.org/docbook/xml/simple/sdocbook/
Любопытно, отчего же мы им не пользуемся?
Впрочем, 106 -- тоже многовато, и наличие спецификации 
не решает проблемы обучения, все равно нужен текст, 
объясняющий, как пользоваться.

> >Не нужно использовать элементы DOCBOOK <option> и <parameter>, поскольку 
> >чрезмерное дробление усложняет и разметку, и восприятие документа, 
> >особенно если для каждого элемента используется свой способ 
> >графического выделения. Во всех случаях вместо <option> и <parameter>
> >следует использовать элемент <command>.
> 
> Способ графического выделения в данном случае не аргумент. Если 
> автор считает нужным выделить option или parameter, это его право 
> и обязанность. К тому же есть ещё refentry, где эти теги особенно 
> важны.

Все приведенные здесь рекомендации по оформлению основаны на моем
опыте разметки документации для ALT. Во всем корпусе документации 
не было _ни одного_ случая, где действительно требовалось бы по 
типографски различать <command>, <option> и <parameter>, если же
различать их с целью поддерживать разные смысловые категории -- 
для чистоты логической разметки, то их следует употреблять 
последовательно _везде_, а это очень много никак не работающей
разметки. Тут уже было как-то обсуждение о разумной степени 
детализации разметки. Исключение <option> и <parameter> -- 
это мое предложение по снижению уровня детализации практически 
без потери смыла. Я просто предлагаю использовать более общую 
смысловую категорию. 

> Я бы вообще предложил не ограничивать авторов в разметке - только 
> от ошибочных тегов.
Тут я занимаю противоположную позицию, признаться. DocBook -- 
слишком детализированная штука, слишком много возможностей, 
слишком пестрый результат при работе многих авторов. 
Понимаете, выбор подмножества я делал ориентируюясь на весь корпус
документации как на целостный документ (поскольку это именно моя 
задача -- сделать ее целостным документом), и разнооформленность 
текстов -- это не технлогический бонус, а сильное препятствие на 
пути к этой целостности. Целостность, кстати, залог того, что 
текст/книга хорошо смотрится в печати.

> >Группа элементов DocBook, предназначенная для оформления ссылок на 
> >литературу, требует для оформления каждой ссылки заполнить достаточно 
> >громоздкую конструкцию библиографического описания в виде XML. Пока не 
> >придуман удобный способ упростить или автоматизировать эту разметку, 
> >используйте обычные сноски для ссылок на литературу. 
> 
> Удобный способ - это WYSIWYM редактор.
Покажите! Как и что он может, что это за редактор?
Буду очень благодарен.

> >	<Ссылки на другие части документа>
> >
> >/использовать Останинский текст/
> 
> Пока не надо. Например, благодаря работе Олега Паращенко в 
> tuning.xsl добавлено преобразование olink в link в случае 
> нахождения ссылки и цели в одном документе.
А что делать? Другого нет, срок мал. Можно ли это быстро обновить?

> Есть предложение забить на db2latex полностью, и использовать для 
> создания печатного вывода OpenOffice. Насколько я понял, 
> существуют стили для преобразования DocBook -> OOo. У OOo сейчас 
> вполне симпатичные pdf получаются.

Я _категорически_ против. Выражаясь афористически (чтобы не впадать 
в очень длинную аргументацию): или я, или OpenOffice! ;)

> Элемент variablelist предназначен также для разметки любых 
> структур, например, дерева каталогов (уточнялось в рассылке 
> docbook at oasis-open.org).
Не совсем понял, что такое "разметка любых структур". Имеется 
в виду что-то вроде списка каталогов (вложенного в несколько 
уровней")?

> >DocBook позволяет давать название любому типу списка 
> >(элемент <title>), однако с точки зрения оформления 
> >и логической структуры документа такие названия обычно 
> >нежелательны. 
> 
> У DocBook TC на этот счёт другое мнение :) Действительно, чем 
> мешает title ?

Он почти никогда не нужен по структуре текста: либо есть вводящее
предложение в абзаце, либо есть заголовок раздела, а список 
и составляет весь его текст. Вводящее предложение в абзаце 
предпочтительнее заголовка списка, потому что обладает бОльшей
синтаксической гибкостью, а заголовок так или иначе придется 
сформулировать в номинативной форме. С чисто полиграфической 
точки зрения заголовки бывают либо у разделов, либо у рисунков/таблиц
и прочих вставных материалов. Озаглавленный список висит как-то между 
тем и другим, создавая непонятную промежуточную категорию и нарушая 
гармонию ;)
Я ответил на Ваш вопрос, чем мне мешает title? ;)

> Я бы всё-таки предпочёл сделать этот текст не новым ALT Docs 
> HOWTO, и параллельным ALT Docs Guidelines или что-нибудь в этом 
> роде. У меня тлеет надежда обновить docs-howto, но несколько 
> другим образом, в частности, используя litprog из стилей и Makefiles.
Но когда? Когда?

-- 
Kirill Maslinsky
ALT Linux Team * Documentation Project   