From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Date: Tue, 16 Nov 2004 14:12:46 +0300 From: Kirill Maslinsky To: ALT Devel discussion list , docs@altlinux.ru Subject: Re: [devel] ALT packaging =?koi8-r?Q?docs_?= =?koi8-r?B?KHdhczog7yDTws/Sy8Ug0NLPx9LBzc0gzsE=?= GTK / GNOME) Message-ID: <20041116111246.GA2158@susanin> Mail-Followup-To: ALT Devel discussion list , docs@altlinux.ru References: <200411100222.28195.lav@altlinux.ru> <200411130058.34344.cray@neural.ru> <20041112235211.GI2422@susanin> <200411130442.23942.cray@neural.ru> Mime-Version: 1.0 Content-Type: text/plain; charset=koi8-r Content-Disposition: inline Content-Transfer-Encoding: 8bit In-Reply-To: <200411130442.23942.cray@neural.ru> User-Agent: Mutt/1.4.2.1i Organization: ALT Linux Team (Docs) X-SpamTest-Status: Not detected X-SpamTest-Version: SMTP-Filter Version 2.0.0 [0129], SpamtestISP/Release Cc: ALTDocumentation Mailing List X-BeenThere: devel@altlinux.ru X-Mailman-Version: 2.1.5 Precedence: list Reply-To: ALT Devel discussion list List-Id: ALT Devel discussion list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 16 Nov 2004 10:56:39 -0000 Archived-At: List-Archive: List-Post: Добрый день! Прошу прощения за задержку с ответом, не хотел отвечать наспех. > > Если сразу править именно исходный > > вариант, предоставленный автором, то всё равно потом придётся дублировать > > изменения в DocBook. Но, конечно, и автору нет смысла пренебрегать чаще > > полезной, чем вредной литературной и прочей правкой. > > Тут есть два момента. Во-1-ых, вы сами сказали, как возвращать редактуру в исходный > текст - неясно. Собственно одна из проблем, которые у меня встали при работе с Docbook в прошлый > раз - это то, что текст в докбуке даже после моих небольших усилий по его разметке, перестал > быть читабельным. Итак, это довод в пользу того, чтобы делать всякую редактуру и корректуру в том же формате, в котором прислал текст автор. Но и в этом случае будут проблемы с синхронизацией с DocBook. Вариант 1: автор предоставляет текст, редактор что-то правит, автор принимает или не принимает правку, и так пока они не договорятся, _после этого_ текст размечается в DocBook. Получается длинный редакторский цикл (минус) и хороший текст (плюс). Если потом автор предоставил новую версию текста -- хо-хо! -- задачка для редактора отследить все изменения (хорошо, если автор пишет в plain text, а если в OOo!), внести необходимую правку в эти изменения, договориться с автором и _внести_ нужные изменения в DocBook. Мучительно хочется упростить кропотливую работу по отслеживанию и внесению изменений. Проблемы бы не было, если бы процесс преобразования в DocBook был автоматическим, но, но... Вариант 2: автор предоставляет текст, редактор _сразу_ размечает его в DocBook, после чего правит авторский и DocBook вариант параллельно (что ужасно), либо автоматически вносит все изменения из докбука в авторский или наоборот (что возможно?). Получается, что сразу есть непроверенного качества текст в докбуке, причём качество текста улучшается по мере прохождения редакторского цикла, и он в любом срезе технически доступен для публикации (плюс), но как избежать двойной ручной работы редактора? (минус, и пребольшой). Если автор потом предоставит новую версию текста, см. вариант 1. > Сама литературная правка, знаете ли, тоже. С бытующей в рашн-комьюити политикой пафосного отношения к документации - > когда оттуда удаляются все мало-мальски скользкие и личные выражения, сленг и все остальное, после чего из него > начисто пропадает все ощущение автора - я не согласен категорически. И не думаю, что мне кто-то сможет объяснить, > почему мой текст, составленный в т.ч. и после того, как я ознакомился с неким прототипом (и возможно не одним), составленном > в достаточно игривой манере (на английском языке, правда), должен становится нудным, тухлым и тусклым документом > со сложноподчиненными выражениями на три страницы в его русской интерпретации. Дабы вести разговор о правке конкретно, я перечёл документацию из rpm-build-python, и посмотрел, что бы мне хотелось в ней изменить при публикации в книжке alt-docs-devel. Там есть опечатки, есть недостающие знаки препинания, есть пара грамматических несогласованностей. Наверное, Вы не станете возражать, что всё это полезно исправить перед публикацией, да и вообще полезно исправить. Есть слово "чбы", которое я бы, грешным делом, заменил на "чтобы", хоть оно и яркий маркер авторского стиля, но всё же не единственный, и, я надеюсь, не самый дорогой автору ;) Что касается жаргона, то ничего криминально-жаргонного я в Ваших текстах не встретил, и почти все термины у Вас, кстати, переведены. Кроме того, некоторая специальность текста не противоречит идее книжки: она же адресована разработчикам или будущим разработчикам, т. е. достаточно хорошо владеющим жаргоном людям, иначе они бы даже не взялись становиться разработчиками. Вот если бы речь шла о документации для пользователя, то никакая жаргонность была бы неуместна, просто потому что текст в этом случае становится совершенно непонятным пользователю, хоть и кажется совершенно ясным специалисту. Единственный вопрос вызвал термин "кляуза" -- я так и не понял, это "clause"? Если так, то русская транслитерация его была бы "клауза", а то получается странная путаница паронимов. С другой стороны, я эту кляузу встречал ещё где-то, и если так уже прочно принято, то лучше, конечно, не ломать традицию. Не могу согласиться с Вашим огульным осуждением редактуры, как "иссушающей" текст. Обилие разговорных (личных) и жаргонных выражений нередко свидетельствует не о блестящем и лёгком авторском стиле, а наоборот, о недостаточном владении регистром письменной речи. Обычно такой текст ещё и малопонятен неподготовленному читателю. Желание редактора это исправить вполне оправданно, а если стиль действительно есть, уверяю Вас, редактор не станет его искоренять. Но, понятно, что это идеальный редактор, которого в природе нет. А так, конечно, бывают и личные тараканы редактора, но есть случаи, которые очевидны большинству читателей, и не только редакторам. Приведу одно предложение из Вашего текста, которое мне бы хотелось перестроить: > Определение зависимостей основано на нахождении в модулях конструкций с > оператором import и использование его параметров для построения > зависимостей. С первого прохода не понять, приходится перечитывать, чтобы вникнуть. Скорее всего этот эффект возникает из-за того, что все действия выражены отглагольными существительными (типа "нахождение") -- классический признак русского канцелярского стиля. Вот переделать бы в глаголы, предложение может стать понятнее, а стиль -- легче. Противник ли Вы и такой правки? > Насколько я готов включать результат такой правки в текст - я, честно говоря, не знаю. Иногда меня удается убедить. А после этого описания задач правки? Впрочем, с Вашим текстом проблем действительно почти нет, однако мне было важно продемонстрировать необходимость правки в общем случае. > > > 4. Python-полиси содержит явные и неявные ссылки на другую аналогичную документацию, в частности из пакета rpm/rpm-build. Будет ли > > > эта документация поддерживаться там же (может быть, уже поддерживается)? > > > Для этого их нужно позиционировать. Для этого нужно чбы было общедоступное место, > в котором эта документация гарантировано есть. Иными словами, нужно чбы коллекция > полиси была замкнутой и мне не нужно было описывать "как поскипать (например) поиск зависимостей > в каталоге /usr/share/doc", зная, что это описано в таком-то месте другой полиси. В текущей ситуации > это боле-менее срабатывает для rpm (-build?) (там где Димина дока про макросы), в остальных случаях > ситуация хуже. Вообще таким общедоступным местом должен стать alt-docs-devel. На него предлагаю и ориентироваться. Димины тексты там есть, если появится необходимость сослаться и на другие полиси, имеющие отношение к сборке пакетов, если смысл заняться и их включением в alt-docs-devel (по крайней мере толкнуть на эту тему авторов и меня). > > А если в начале каждого полиси, опубликованного в alt-docs-devel, поставить обязательную краткую справку: > > к какой версии соответствующего продукта этот > > Как бы еще обязать читателя ее прочитывать? Знаете, я работал над одной книжечкой старательно протестировал > все примеры и выписал там же все номера версий использованноег софта и т.д. т.п. Через два года после издания > посыпались жалобы читателей что книга "ужасна" так как "ни один" пример не работает. Объяснение очень простое: > за два года сменились мажоры подавляющего большинства продуктов. А вспомнил я это как пример отношения > читателей к таким комментариям. Конечно, я всегда могу отмазаться, показав комментарий - но потребителю от этого > не легче. Но тогда проблема и с замечанием, что текст мог устареть -- пользователь точно так же может его проигнорировать и недоумевать потом. Лучше уж предоставить побольше информации заинтересованным лицам. > > текст относится, какой он имеет статус (пробный, предложение, обязательный > > и общепринятый, устаревающий и т. п.), и также _какие ещё_ версии существуют > > наряду с ним, _где_ и _с каким статусом_). > Я не случайно сказал про ветви. Так сложилось (и я считаю что это правильно рад тому, что хотя бы в одном случае это удалось сложить), > у нас почти всегда активны минимум две ветви полиси: в дедале и в сизифе. В дедале типа действщая модель в натуральную > величину. Ну так это бы нужно и написать в начале полиси, логично? Я не нашёл, м. б. пропустил? -- Kirill Maslinsky ALT Linux Team * Documentation Project