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

[Vitaly Ostanin]

Kirill Maslinsky пишет:
> Привет еще раз!
> 
>>Хорошо, давайте так и сделаем, как временную меру. Или как форк 
>>от docs-howto. Или давайте придумаем логическое разбиение 
>>docs-howto на разделы. Например:
> 
> А давайте просто изменим мой текст так, чтобы он идеологически
> не выбивался из docs-howto. Я, на самом деле, готов отказаться
> от своего пафоса ограничивать автора в разметке, но мне кажется, 
> что рекомендации, как и что стоит размечать (своего рода вводное
> практическое руководство по разметке в docbook), все равно нам
> понадобятся. И уже написанный раздел несложно сделать таким 
> руководством, несколько изменив. 

Я нисколько не против рекомендаций :)

> Начиная с заголовка: заменить "Правила разметки" на "Рекомендации...", 
> все предписательные замечания по тексту сделать рекомендательными, 
> + учесть Ваши замечания. Только я хотел бы оставить в тексте 
> термин "понятие" (entity), в качестве воли автора, которую Вы так убеждали
> меня уважать в предшествовавшем обсуждении ;)

Кроме как в этой переписке, я не видел ни одного перевода 
entities как "понятий", и уже сталкивался с ситуацией, когда 
работа стопорится исключительно из-за попыток говорить на разных 
языках.

Вам действительно так важно использовать перевод "понятие" ?

> Тогда, соответственно, куда можно поставить этот раздел в предложенном
> Вами оглавлении:
> 
> 
>>Цели проекта
>>История проекта, в том числе технологическая
>>Текущее состояние проекта, выбранные формат и технология
>>TODO проекта (можно в виде appendix)
>>Жизненный цикл документа от создания до публикации
>>Создание документов
>> - краткое введение в DocBook
> 
> вот это -- практическое руководство, или это просто 
> характеристика технологии DocBook со ссылками?

Просто краткое руководство, лично мне уже не важно, как оно будет 
выглядеть :) Кстати, лучше так:
- краткое введение в XML
- краткое введение в DTD DocBook

>> - возможно, перевод описаний основных тегов DocBook DTD, можно 
>>в виде appendix
>> - принятые соглашения по стилистике
> 
> А их нет, на самом деле, да и не нужно, как мне кажется, 
> потому что в этот раздел будет практически нечего 
> написать кроме очевидных рекомендаций, что сленг не 
> нужно использовать и что документация -- это письменная 
> речь со всеми вытекающими. Любой грамотный автор и так это 
> понимает, а неграмотный все равно не соблюдёт.

Есть ещё переходная стадия :) Например, не все знают, что не 
стоит ставить крайние пробелы в inline тегах.

>> - принятые соглашения по оформлению
> 
> или это -- практическое руководство по разметке?

Что-то вроде. Например, как делать плавающие картинки, как 
указывать автора и т.п.

Я привёл это примерно оглавление только как список того, что 
вообще должно быть. Где именно и в каком порядке - пока не так уж 
важно.

> или же имеется в виду оформление типа "какие знаки ставить 
> в конце пунктов перечисления" (у Вас, кстати, на эту тему
> неверные сведения приводятся в docs-howto, нужно исправлять). 

Легко :) Только расскажите, как правильно.

<skipped/>

> Кстати, должен обратить Ваше внимание, что в этом
> отношении в docs произошли значительные изменения. 
> В частности, сейчас каталоги admin, user, install в 
> cvs -- полностью obsoleted, потому что изменилась 
> сама структура документации. На эту тему у меня тоже 
> есть черновик описания текущего положения дел, 
> давайте его обсудим отдельным тредом (сейчас отправлю).

Да, прочитал.

>> - работа со средой разработки (cvs, subversion, публикация 
>>результатов на web)
>>Описание системы публикаций
>> - общая схема
>> - документация по Makefile-ам (цели, параметры)
> 
> А можно сейчас сюда включить текст Олега Паращенко про 
> Makefile'ы? Это бы нужно в Мастер.

Это вопрос скорее к Олегу, лично я не против.

<skipped/>

-- 
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/20040810/b9d9635d/signature.bin