From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Date: Sat, 13 Nov 2004 02:52:11 +0300 From: Kirill Maslinsky To: ALT Devel discussion list Subject: Re: [devel] ALT packaging =?koi8-r?Q?docs_?= =?koi8-r?B?KHdhczog7yDTws/Sy8Ug0NLPx9LBzc0gzsE=?= GTK / GNOME) Message-ID: <20041112235211.GI2422@susanin> Mail-Followup-To: ALT Devel discussion list References: <200411100222.28195.lav@altlinux.ru> <200411121216.51342.cray@neural.ru> <20041112105016.GA2422@susanin> <200411130058.34344.cray@neural.ru> Mime-Version: 1.0 Content-Type: text/plain; charset=koi8-r Content-Disposition: inline Content-Transfer-Encoding: 8bit In-Reply-To: <200411130058.34344.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 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: Fri, 12 Nov 2004 23:49:50 -0000 Archived-At: List-Archive: List-Post: Доброе, уже, наверное, утро. > > Надеюсь что Вам, как автору, будет несложно обновлять свою документацию ещё в одном месте (это можно даже автоматизировать). > > Чего уж проще: rpm -Uvh rpm-build-python; cvs commit; > :) Этот разговор я хотел бы продолжить в docs@, куда и направляю копию, но если кто-то из тех подписчиков devel@, кто не читает docs@, захочет что-нибудь добавить или откомментировать, пожалуйста, не стесняйтесь это делать и здесь. > > Предложения и замечания по организации ``репозитория исходных текстов документации'' необходимы и будут очень кстати в рассылке docs@. > > Я пока предложений высказывать не буду, хочу только получить ответы на неск. вопросов, часть из которых навеяна прошлым опытом: > > 1. Если у нас уже какая-либо практика ведения в док буке именно ПОЛИСИ на пакетирование? Вопрос задан потому, > что есть несколько характерных особенностей, которые я заметил по крайней мере на своей практике, и мне бы хотелось понять, > как это будет решаться. Пока единственное полиси в докбуке -- alt-packaging, которое я обновил по новой версии текста от Димы Левина перед выходом ALM 2.4. Так что нет практики. Поскольку сборник полиси по проекту Sisyphus всё равно нужен, такую практику придётся создавать. > 2. Будут ли документы полиси опубликованы где-л. в общедоступном месте? Особенност вопроса в том, что многие документы > постоянно обновляются, и их обновление должно незамедлительно публиковаться. На тьекущий момент - все доки сбраны в одном месте, > в пакете rpm-build-python - все решается просто. Если в инет будет выкладыватся версия полугодовой давности - вреда будет больше чем пользы. > Вопрос даже не в том, что информация может перестать быть валидной - это для полиси не характерно - вопрос в том, что полиси не содержащая > последние (наиболее актуальные) изменения будет создавать потребителю ложную видимость знакомства с полиси. Все документы из пакетов alt-docs-* скоро таки будут опубликованы на сайте docs.altlinux.ru, и там будут всегда последние версии. Сейчас последние версии документов представлены в Сизифе в пакетах alt-docs-*. Если удастся хорошо организовать систему обновлений документации, так что участники проекта docs сразу и непосредственно будут узнавать о выходе новой версии полиси, то обновление текста в DocBook и выкладывание в сеть -- дело техники. Перечисленные выше причины, пожалуй, свидетельствуют за то, чтобы объявить обновление полиси (т. е. пакета alt-docs-devel) приоритетной задачей. Это будет оправданно, если этот пакет действительно будет востребован, как отражающий текущее состояние разработки в Сизифе: как справочник для опытных и руководство для начинающих. Пока мне кажется, что так и должно произойти. > 3. Как будут решаться вопросы с литературной правкой? Чгря даже на случае с Zope у меня были некоторые проблемы, а то была все-таки > более менее старательно написанная документация, тогда как в случае с полиси литературность я однозначно приношу в жертву оперативности > обновления и однозначности текста. Для литературной правки есть отличный момент перехода текста из авторского варианта в DocBook. Можно и нужно делать не только разметку текста, но и редактуру (так, впрочем, почти всегда и происходит). Серьёзная проблема, которой я пока не могу предложить никакого практического решения -- как потом обратно вносить редактуру в авторский текст? Если сразу править именно исходный вариант, предоставленный автором, то всё равно потом придётся дублировать изменения в DocBook. Но, конечно, и автору нет смысла пренебрегать чаще полезной, чем вредной литературной и прочей правкой. > 4. Python-полиси содержит явные и неявные ссылки на другую аналогичную документацию, в частности из пакета rpm/rpm-build. Будет ли > эта документация поддерживаться там же (может быть, уже поддерживается)? Честно говоря, лучше все неявные ссылки сделать явными. Уверен, что это во всех случаях возможно и в подавляющем большинстве -- полезно. README.ALT из rpm -- интегрирована с alt-packaging в том же пакете alt-docs-devel (там тексты несколько пересекались). Раз уж оно туда попало, то поддерживаться будет. Если получится схема поддержки полиси, rpm policy тоже будет поддерживаться по этой схеме. Про документацию из rpm-build я просто не знаю -- вопрос к Вам и к авторам: что из этого имеет отношение к Сизифу и нужно в alt-docs-devel? Будем включать. > 5. Как будет решаться вопрос с версиями, а самое главное - с паралельными ветвями полиси? Сейчас версия полиси лежит в пакете rpm-build-python > и возможность установки и использования этого пакета примерно совпадает с границами применимости полиси, это, может быть, не совсем > удобно, зато управляемо, объяснимо и воспроизводимо. > > В любом случае, я прошу, до тех пор, пока эта технология не будет обкатана, что бы на видном месте > стояло следующие замечание: "это неофициальная версия полиси, которая, возможно, искажена или устарела. > Официальная версия содержится в пакете rpm-build-python" А если в начале каждого полиси, опубликованного в alt-docs-devel, поставить обязательную краткую справку: к какой версии соответствующего продукта этот текст относится, какой он имеет статус (пробный, предложение, обязательный и общепринятый, устаревающий и т. п.), и также _какие ещё_ версии существуют наряду с ним, _где_ и _с каким статусом_). Поскольку это один абзац в начале текста, при смене позиций (например, смене статуса текущего опубликованного документа с общепринятого на устаревший и под.) -- обновление его в online-версии alt-docs-devel можно сделать _очень оперативно_. Это не предполагает, что нужно сразу разметить в DocBook и опубликовать новую версию полиси, на что нужно время. Нужно только, чтобы автор позаботился об обновлении одного абзаца о статусе текста. Мне такой вариант представляется гораздо более информативным, чем оговорка о возможной (но необязательной) неадекватности документа. Более того, он позволяет предавать гласности спорные предложения, не дожидаясь единогласия (которое может и не наступить) и при этом никого не вводя в заблуждение относительно их статуса: просто нужно оговорить, что перед читателем -- предложение. Разработка, в конце концов, это поиск, и документация должна это отражать. При всем alt-docs-devel я готов в начале поставить объяснение его статуса: отражает текущее состояние разработки, поэтому если Вы хотите знать наверняка -- не полагаётесь на печатную версию или пакет в дистрибутиве, смотрите последнюю версию в Сизифе или на сайте. -- Kirill Maslinsky ALT Linux Team * Documentation Project