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

[Vitaly Ostanin]

Kirill Maslinsky пишет:
> Привет!
> 
> Спасибо за развернутые и дельные комментарии к черновику. 
> Я на некоторые из них хотел бы ответить, с остальными согласен, 
> поэтому просто их пропущу. Но прежде частных комментариев 
> хотелось бы сделать резюме: 
> 
> Насколько я понял, Ваша общая идея примерно в том, что важнее 
> найти инструмент, с помощью которого можно было бы писать текст
> с нужной разметкой, чем объяснять и указывать автору, как и что 
> нужно размечать. 

Скорее, не важнее, а первичнее. Если автору просто не комфортно 
писать текст, ему гораздо сложнее сосредоточиться на смысле текста.

> Я совершенно согласен с тем, что инструмент нужен
> и готов включаться в его поиски/разработку, но тем не менее
> я глубоко уверен, что указания и объяснения автору нужны даже 
> больше. 

Указаний и объяснений полно, просто они в неудобном виде.

> Потому что никакая программа не укажет человеку, что 
> имена файлов и примеры команд нужно выделить специальным тегом, 
> для списков использовать специальные элементы, а не просто цифры и т. д., 
> короче говоря, не заставит его делать правильную логическую разметку.

Заставлять и не нужно. Нужно сделать в редакторе плагин, 
сортирующий теги конкретно взятого DTD по категориям - листинги, 
картинки, списки и т.п. Это, кстати, несложно, и в XML-based 
схемах DocBook такие категории наверняка будут.

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

Хорошо, давайте так и сделаем, как временную меру. Или как форк 
от docs-howto. Или давайте придумаем логическое разбиение 
docs-howto на разделы. Например:

Цели проекта
История проекта, в том числе технологическая
Текущее состояние проекта, выбранные формат и технология
TODO проекта (можно в виде appendix)
Жизненный цикл документа от создания до публикации
Создание документов
  - краткое введение в DocBook
  - возможно, перевод описаний основных тегов DocBook DTD, можно 
в виде appendix
  - принятые соглашения по стилистике
  - принятые соглашения по оформлению
  - примеры типовой разметки (картинки, ссылки)
  - перечисление редакторов
Среда разработки документов
  - описание разбиения на каталоги, их назначение
  - работа со средой разработки (cvs, subversion, публикация 
результатов на web)
Описание системы публикаций
  - общая схема
  - документация по Makefile-ам (цели, параметры)
  - документация по XSL-стилям (назначение, возможности, параметры)
Релизы документации (когда создаются, каким образом)
Краткое описание сайта проекта, в том числе его внутренней структуры

В каждом разделе должен быть список литературы/ссылок, и в конце 
docs-howto все списки/ссылки должны быть собраны вместе.

Просто гибрида нового варианта и старого я хотел бы избежать.

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

Честно говоря, поначалу он мне тоже не понравился, но потом я к 
нему привык, и у меня сложилось впечатление, что это достаточно 
устоявшийся термин в русскоязычной среде работающих с XML.

> Перевод entity как "понятие" гораздо более удачен, поэтому 
> я и придерживался его, указывая в скобках (entity). 

Уж лучше тогда обойтись вообще без перевода.

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

Сомневаюсь, что и объяснение смысла автору возможно :) Повторюсь, 
категоризация тегов сильно упростит жизнь автору. Как и удобный 
показ соответствующей документации из DocBook TDG.

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

Потому что ограничение в тегах - не выход.

> Впрочем, 106 -- тоже многовато, и наличие спецификации 
> не решает проблемы обучения, все равно нужен текст, 
> объясняющий, как пользоваться.

Именно - пусть будет текст, обучающий, как пользоваться. 
Использование DocBook, кстати, помогает структурировать написание 
документа.

Когда автор более менее осваивается в DTD, он понимает, что 
где-то раньше напортачил, или понял, как логичнее преподнести 
какую-то часть текста. Просто потому, что он раньше не знал, что 
таким-то тегом сделать правильнее или удобнее.

Да, в DocBook есть похожие теги, ну и что? Они и обрабатываются 
стилями как похожие теги.

С ростом понимания DocBook или потребности в качественном 
документе нужны ранее неиспользованные теги. Так зачем их 
отрезать на уровне DTD ? Не нравится - можно не использовать, в 
конце концов можно обойтись только section/title/para.

А когда понадобится сделать детальный разбор листинга или 
картинку в разных вариантах для разных выводов? Менять DTD ?

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

Мои, в общем, тоже :) И не только для ALT.

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

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

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

При использовании DocBook/XML хороший внешний вид достигается 
правильной настройкой стилей, а не дополнительными рамками для 
авторов.

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

Вот это и есть первоочередная проблема на данный момент, IMHO, и 
несколько обсуждений на конференции и фестивале это подтверждают. 
Есть много людей, которые хотят работать с документацией, но не 
могут это сделать.

Свободного и доступного WYSIWYM редактора, корректно работающего 
с документами из cvs docs, сейчас нет. Есть перспективные 
редакторы (удобные для массового использования, я не имею в виду 
emacs/vim):

http://conglomerate.org/
http://tkxmlive.sourceforge.net/index.html
http://vex.sourceforge.net/

Но все они сыроваты для практического использования с cvs docs. 
Есть ещё вариант со стилями импорта/экспорта из OOo, каковые 
собирался показать Анатолий Якушин после отпуска.

И есть перспективные платформы, на которых можно сделать такой 
редактор:

- mozilla
- openoffice.org
- eclipse
- связка из кроссплатформенных юникодных компонентов, например, 
тот же набор libxml2-python/python/pygtk2/pyglade/gtk2

Что должен уметь такой редактор, готов обсудить в отдельном треде.

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

Быстро - нет. Если так нужно, используйте, конечно.

>>Есть предложение забить на db2latex полностью, и использовать для 
>>создания печатного вывода OpenOffice. Насколько я понял, 
>>существуют стили для преобразования DocBook -> OOo. У OOo сейчас 
>>вполне симпатичные pdf получаются.
> 
> Я _категорически_ против. Выражаясь афористически (чтобы не впадать 
> в очень длинную аргументацию): или я, или OpenOffice! ;)

Лучше просто аргументацию, этот афоризм совершенно неубедителен :)

OOo создаёт на выходе PDF хорошего качества с возможностью 
предварительной довёрстки, и даже визуальной.

TeX в этом смысле совсем хорош, но вот db2latex - совсем плох.

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

Да, или XML дерева - любой древовидной структуры.

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

Лично Вам - да :) Но я бы не стал говорить "почти никогда не 
нужен" - мне заголовки в списках неcколько раз понадобились.

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

После выхода M2.4. Кстати, если меня периодически пинать, процесс 
ускоряется :) Просто меня иногда заваливают на основной работе и 
я забываю про docs@ :(

PS Обсуждения отдельных инструментов или платформ для редактора 
давайте выносить в отдельные треды, pls.

-- 
Regards, Vyt
mailto:  vyt at vzljot.ru
JID:     vyt at vzljot.ru
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 252 bytes
Desc: OpenPGP digital signature
Url : http://lists.altlinux.ru/pipermail/docs/attachments/20040809/160ba50a/signature.bin