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

[Kirill Maslinsky]

Добрый день!

Долго собирался ответить на это письмо, и вот почему.
Честно говоря, я хочу предложить свести к минимуму, а то и вовсе свернуть общетеоретическую дискуссию о литературной правке и редактуре. 
Потому что есть основательное подозрение, что наши мнения по большинству 
вопросов совпадают, а весь дискуссионный запал происходит только от того, 
что Вы несколько заостряете позицию автора, а я -- редактора. Тем более
что Вы отделяете литературную правку от всякой прочей, а я, наоборот, говорю о единой Правке. И с нашими формулировками мы ещё много слов разбросаем, пока
договоримся явно. ;) 

Когда я заводил разговор о правке python-policy, на самом деле цель была
в том, чтобы понять: следует ли документацию из rpm-build-python включать в книжку про ALT и Сизиф (alt-docs-devel) целиком и в неизменном виде и в каком порядке (doc,policy,faq,SAMPLE.spec)? Или же нужно эти тексты как-то перестроить, возможно, 
снабдить введением? Вам, наверное, несложно сформулировать мнение по этому
вопросу, тем более что книжка существует во вполне конкретном виде:
всего-то требуется посмотреть оглавление и несколько страниц.

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

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

какая есть у меня, rpm-build-python-0.12-alt3

> > Приведу одно предложение из Вашего текста, которое мне бы хотелось перестроить:
> 
> > > Определение зависимостей основано на нахождении в модулях конструкций с
> > > оператором import и использование его параметров для построения
> > > зависимостей.
> 
> Приведите ваш вариант? 
Проблема в том, что чтобы переписать, нужно хорошо представлять, о чём речь.
Я почти не представляю, а из имеющегося текста толком не понять ;)
Попытался записать то, что понял я, где добавил отсебятину, там поставил (?). 

Вместе с предыдущим абзацем:

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

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

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

> > Вообще таким общедоступным местом должен стать alt-docs-devel. На него 
> 
> Что-то у меня создается такое ощущение, что моей головой хотят проломить стену. Имейте ввиду, что

И вовсе нет. Я просто хотел с Вами обсудить, как лучше включить 
Pythom policy в alt-docs-devel с наибольшей выгодой для Python policy 
и alt-docs-devel. И как организовать поддержку получившегося документа 
в актуальном состоянии. 

> > > Я не случайно сказал про ветви. Так сложилось (и я считаю что это правильно  рад тому, что хотя бы в одном случае это удалось сложить),
> > > у нас почти всегда активны минимум две ветви полиси: в дедале и в сизифе. В дедале типа действщая модель в натуральную 
> > > величину.
> 
> Это не является python-специфичным. Чгря, по-моему это стоит попробовать адаптировать к повсеместному введению, а раз так - то это
> текст для другой полиси, которая, я надеюсь, когда-либо все-таки появится.

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

> PS: Кстати, пользуясь случаем, хотел бы попросить неизвестного мне (пока) добровольца, занятся
> разработкой полиси на документацию к пакетам и воплощением ее положений в реальную жизнь.

Неизвестного и мне (пока).

-- 
Kirill Maslinsky
ALT Linux Team * Documentation Project