From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: From: Andrey Orlov To: ALT Devel discussion list Subject: Re: [devel] ALT packaging docs (was: =?koi8-r?b?7yDTws/Sy8Ug0NLPx9LBzc0gzsEgR1RLIC8=?= GNOME) Date: Sat, 13 Nov 2004 04:42:23 +0300 User-Agent: KMail/1.7.1 References: <200411100222.28195.lav@altlinux.ru> <200411130058.34344.cray@neural.ru> <20041112235211.GI2422@susanin> In-Reply-To: <20041112235211.GI2422@susanin> MIME-Version: 1.0 Content-Type: text/plain; charset="koi8-r" Content-Transfer-Encoding: 8bit Content-Disposition: inline Message-Id: <200411130442.23942.cray@neural.ru> Cc: docs@altlinux.ru 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: Sat, 13 Nov 2004 01:34:38 -0000 Archived-At: List-Archive: List-Post: On Saturday 13 November 2004 02:52, Kirill Maslinsky wrote: > > 3. Как будут решаться вопросы с литературной правкой? Чгря даже на случае с Zope у меня были некоторые проблемы, а то была все-таки > > более менее старательно написанная документация, тогда как в случае с полиси литературность я однозначно приношу в жертву оперативности > > обновления и однозначности текста. > > Для литературной правки есть отличный момент перехода текста из авторского > варианта в DocBook. Можно и нужно делать не только разметку текста, но и > редактуру (так, впрочем, почти всегда и происходит). Серьёзная проблема, > которой я пока не могу предложить никакого практического решения -- как потом > обратно вносить редактуру в авторский текст? Если сразу править именно исходный > вариант, предоставленный автором, то всё равно потом придётся дублировать > изменения в DocBook. Но, конечно, и автору нет смысла пренебрегать чаще > полезной, чем вредной литературной и прочей правкой. Тут есть два момента. Во-1-ых, вы сами сказали, как возвращать редактуру в исходный текст - неясно. Собственно одна из проблем, которые у меня встали при работе с Docbook в прошлый раз - это то, что текст в докбуке даже после моих небольших усилий по его разметке, перестал быть читабельным. Когда туда начали добавлятся более-менее серьезные усилия специалистов, я просто перестал ориентироваться в тексте и его обновление стало очень мучительным (у меня довольно страннное восприятие текста, я помню сформатированный текст чисто зрительно очень большими кусками, и за счет этого легко в нем ориентируюсь и быстро позиционируюсь в нужном месте: но текст для этого должен быть более-менее аккуратно сформатирован, иначк узнаваемость теряется - в постоянном "шуме" ориентироаться невозможно; цитаты исходного кода с заменами < > на < > уничтожили один из основных ориентиров (код я помню лучше, чем пояснения к нему), кроме того, я легко выхватываю из текста ключевые слова (там Zope, Python) когда их тоже стали заменять на &altlinux; в общем, для меня настал крындец). Я долгое время думал, что это моя личная проблема, но вот на недавнем линуксфесте узнал, что проблема достаточно общая. Сама литературная правка, знаете ли, тоже. С бытующей в рашн-комьюити политикой пафосного отношения к документации - когда оттуда удаляются все мало-мальски скользкие и личные выражения, сленг и все остальное, после чего из него начисто пропадает все ощущение автора - я не согласен категорически. И не думаю, что мне кто-то сможет объяснить, почему мой текст, составленный в т.ч. и после того, как я ознакомился с неким прототипом (и возможно не одним), составленном в достаточно игривой манере (на английском языке, правда), должен становится нудным, тухлым и тусклым документом со сложноподчиненными выражениями на три страницы в его русской интерпретации. В общем, по-моему тут происходит явная подмена науки наукообразием. Другая, столь же острая проблема (особенно в отношении Полиси), это перевод терминов. Может быть, кому-то после этого текст становится понятным. Но тем, для кого он писался, и даже тому __кем__ он писался текст перестает быть понятен абсолютно. Насколько я готов включать результат такой правки в текст - я, честно говоря, не знаю. Иногда меня удается убедить. > > 4. Python-полиси содержит явные и неявные ссылки на другую аналогичную документацию, в частности из пакета rpm/rpm-build. Будет ли > > эта документация поддерживаться там же (может быть, уже поддерживается)? > > Честно говоря, лучше все неявные ссылки сделать явными. > Уверен, что это во всех случаях возможно и в подавляющем большинстве -- > полезно. Для этого их нужно позиционировать. Для этого нужно чбы было общедоступное место, в котором эта документация гарантировано есть. Иными словами, нужно чбы коллекция полиси была замкнутой и мне не нужно было описывать "как поскипать (например) поиск зависимостей в каталоге /usr/share/doc", зная, что это описано в таком-то месте другой полиси. В текущей ситуации это боле-менее срабатывает для rpm (-build?) (там где Димина дока про макросы), в остальных случаях ситуация хуже. Даже от участвующих в текущем треде людей я пару раз получал отсылки к документации, якобы формализующей то-то и се-то, документация была - а вот ни малейшего упоминания того-то и сего-то - не было. > > 5. Как будет решаться вопрос с версиями, а самое главное - с паралельными ветвями полиси? > > Сейчас версия полиси лежит в пакете rpm-build-python > > и возможность установки и использования этого пакета примерно совпадает с границами > > применимости полиси, это, может быть, не совсем > > удобно, зато управляемо, объяснимо и воспроизводимо. > А если в начале каждого полиси, опубликованного в alt-docs-devel, поставить обязательную краткую справку: > к какой версии соответствующего продукта этот Как бы еще обязать читателя ее прочитывать? Знаете, я работал над одной книжечкой старательно протестировал все примеры и выписал там же все номера версий использованноег софта и т.д. т.п. Через два года после издания посыпались жалобы читателей что книга "ужасна" так как "ни один" пример не работает. Объяснение очень простое: за два года сменились мажоры подавляющего большинства продуктов. А вспомнил я это как пример отношения читателей к таким комментариям. Конечно, я всегда могу отмазаться, показав комментарий - но потребителю от этого не легче. > текст относится, какой он имеет статус (пробный, предложение, обязательный > и общепринятый, устаревающий и т. п.), и также _какие ещё_ версии существуют > наряду с ним, _где_ и _с каким статусом_). Я не случайно сказал про ветви. Так сложилось (и я считаю что это правильно рад тому, что хотя бы в одном случае это удалось сложить), у нас почти всегда активны минимум две ветви полиси: в дедале и в сизифе. В дедале типа действщая модель в натуральную величину. > При всем alt-docs-devel я готов в начале поставить объяснение его статуса: > отражает текущее состояние разработки, поэтому если Вы хотите знать наверняка -- > не полагаётесь на печатную версию или пакет в дистрибутиве, смотрите последнюю > версию в Сизифе или на сайте. Да, конечно. По крайней мере первое время. -- WthBstRgrds -- Андрей Орлов -- --- http: www.neural.ru, mail: cray@neural.ru, jid: cray@altlinux.org --- ----------------------------------------