[docs] О литературной правке ( было: ALT packaging docs)

[Andrey Orlov]

On Monday 22 November 2004 17:45, Kirill Maslinsky wrote:
> Долго собирался ответить на это письмо, и вот почему.
> Честно говоря, я хочу предложить свести к минимуму, а то и вовсе свернуть 
> общетеоретическую дискуссию о литературной правке и редактуре.  

Я с этим предложением согласен, в то же время должен отметить, что
по крайней мере с моей стороны, большая часть дискуссии вызвана либо
отсутствием, либо лично моим незнакомством с какой-либо полиси на 
ведение документации в ALT. Пункты полиси можно критиковать, развивать
и отменять. В то же время, им можно (нужно) следовать. Это удобно,
даже если не со всеми п. полиси согласен. Ну а за отсутствием (или незнакомством)
таковой, любая дискуссия на эьу тему грозит превратится в пустопорожний треп, 
поддерживать который просто нет сил ;)

> Когда я заводил разговор о правке python-policy, на самом деле цель была
> в том, чтобы понять: следует ли документацию из rpm-build-python включать 
> в книжку про ALT и Сизиф (alt-docs-devel) целиком и в неизменном виде и 

Я думаю, что полиси стоит включать только в том случае, если мы вообще
собираемся прикладывать какие-либо усилия к стандартизации процесса
поддержки - разработки. Т.е. только полиси на python - наверно не стоит
включать. Полиси на полиси, Полиси на пакетирование вообще и Полиси
на python как частный случай - да, это может быть даже стоит. Хотя,
наверно не в текущем виде.

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

> в каком  порядке (doc,policy,faq,SAMPLE.spec)? 

если включать, то policy & faq - в порядке нумерации, doc - либо не включать вообще, либо оформить
как приложения.

> Или же нужно эти тексты как-то перестроить, возможно,    
> снабдить введением? Вам, наверное, несложно сформулировать мнение по этому
> вопросу, тем более что книжка существует во вполне конкретном виде:
> всего-то требуется посмотреть оглавление и несколько страниц.

Где их взять?

> В зависимости от этого получится либо исправленная редакция существующей
> документации rpm-build-python, либо отдельный документ, "глава про
> упаковку модулей и программ на Питоне в Сизифе". Либо получится и то, 

Отдельный документ может внезапно очень быстро устареть :(

> > Зря надеятесь. Почитайте на досуге багзиллу. Кстати, NS его, вроде, везде 
> > исправил? Вы какую версию смотрели?
> 
> какая есть у меня, rpm-build-python-0.12-alt3

В общем, это недопустимо старая версия.

> Вместе с предыдущим абзацем:
> Список(?) зависимостей модуля или программы на языке "Python" от 

;)) Вы уверены, что это именно список, а не кортеж или словарь? Я вот не уверен,
так что постарался бы избежать ненужной детализации и оставил :

"Зависимости модуля на языке python от других модулей ..."

> других модулей(?) можно получить автоматически. 

"...нужно..."

> Автоматическое определение зависимостей позволяет обеспечить полноту установки среды для любой программы  
> на "Python" и облегчает(?) разбиение пакетов на отдельные компоненты.

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

    Автоматическое определение зависимостей для модулей и программ на языке
    "Python" допускает разбиение пакетов на отдельные компоненты,
    обеспечивая возможность контроля полноты установки среды.

Что, по моему, более точно отражает мою мысль. Хотя вот так, наверно, будет
лучше:

    Автоматическое определение зависимостей для модулей и программ на языке
    "Python" обеспечивает возможность контроля полноты установки среды,
    что допускает разбиение пакетов на отдельные компоненты.

> Определение зависимостей основано на поиске в модуле или программе(?)
> конструкций с оператором import. Параметры найденных import используются для
> построения списка(?) зависимостей. 

Я не слишком согласен с каким-то странным противопоствлением модуля и программы и
мне не нравится ненужная детализация реализации (я про список). Разбить фразу
на две - это мысль, которую стоит рассмотреть: смысл ощутимо изменился - 
но остался эквивалентным.

> Собственно, эти вопросики отражают, где в тексте были непонятные моменты, 
> которые пришлось додумывать.

Я откомментировал, чбы что-то такое проиллюстрировать. Наверно то,
как редактура может случайно исказить смысл в погоне за литературностью ;),
я немного утрировал, конечно.

> В прояснении этих непонятностей я и вижу  
> задачу редактуры. А уж стиль... не уверен, что мой стиль лучше ;)

Разумеется,  непонятности в тексте нужно искать и устранять ;), только
обычно вводят "литературного" редактора и "научного". И кто именно
из них занимается прояснением .... я затрудняюсь сказать.

> А вот это как раз годится в общую часть (введение) alt-docs-devel. И я могу
> попробовать там это сформулировать. Даже не на правах полиси, а не правах 
> рационализаторского предложения, рекомендованного ко введению ;)

Полиси и рождаются из документированных рацух ;), так что,
конечно, формулируйте.

-- 
WthBstRgrds -- Андрей Орлов --  
 --- http: www.neural.ru, mail: cray на neural.ru, jid: cray на altlinux.org ---
----------------------------------------