Docs: различия между версиями

Материал из ALT Linux Wiki
(Import from freesource.info)
 
Нет описания правки
Строка 1: Строка 1:
[[Category:Devel]]
[[Category:Devel]]
{{MovedFromFreesourceInfo|AltLinux/Sisyphus/devel/Docs}}
== Правила упаковки документации ==


=== Советы по упаковке документации ===
Упаковке подлежит вся документация, поставляемая с программой/библиотекой, за исключением
* стандартных файлов INSTALL, содержащих строку "These are generic installation instructions.". Эти файлы создаются путем копирования /usr/share/automake-*/INSTALL в процессе работы automake.
* пустых файлов NEWS и т.д.
* файлов [[SpecTips/License|стандартных лицензий]]
* руководств по сборке/установке программы, содержащие тривиальные рекомендации про ./configure && make && make install
* файлов вида ChangeLog, генерирующихся из системы контроля версий и содержащих просто список коммитов


Упаковке подлежит вся документация, поставляемая с программой/библиотекой, за исключением отдельных случаев:
Документация для разработчиков (описание API, примеры и т.д.) пакуется, в зависимости от размера
* Стандартные файлы INSTALL (см. [http://lists.altlinux.org/pipermail/devel/2006-January/028534.html письмо lav@]), содержащие строку "These are generic installation instructions.". Эти файлы создаются путем копирования /usr/share/automake-*/INSTALL в процессе работы automake.
* в -devel-пакет, если размер документации меньше остального содержимого пакета
* Пустые файлы NEWS и т.д.
* в -doc (или -devel-doc, если в -doc находится документация для пользователей), в противном случае
* Файлы [[SpecTips/License|стандартных лицензий]]
* Руководства по сборке/установке программы, содержащие тривиальные рекомендации про ./configure && make && make install
:
:
Девелоперская документация библиотек, нужная лишь для разработки использующих эти библиотеки программ (руководства по API, примеры и т.д.) пакуются либо в -devel, либо в отдельный пакет (см. ниже).


Если объем документации сравним (а то и резко больше) объема остальных файлов пакета (как правило это пакет lib*-devel, содержащий небольшой /usr/include и более тяжелый /usr/share/doc, например [https://bugzilla.altlinux.org/show_bug.cgi?id=5935 старый libalsa-devel], стоит задуматься о выделении /usr/share/doc (возможно, за исключением NEWS и т.д.) в отдельный пакет lib*-doc либо lib*-devel-doc <tt>(нужно определиться с политикой именования)</tt>. Примеры использования библиотеки/модуля, если они достаточно тяжелые, стоит паковать в отдельный foo-examples.
Объёмные файлы Changelog и NEWS необходимо сжимать перед упаковкой. Сжатию подлежат файлы более <tt>100 килобайт</tt>, а также файлы, сжатием которых достигается значительный выигрыш в размере бинарного либо установленного пакета.
 
Часто пакет содержит очень объемистый файл Changelog и/или (реже) NEWS. Такие файлы необходимо сжимать перед упаковкой. Сжатию подлежат файлы более <tt>100 килобайт</tt>, а также файлы, сжатием которых достигается значительный выигрыш в размере бинарного либо установленного пакета.
 
=== Ссылки ===
* [http://lists.altlinux.ru/pipermail/devel/2006-February/028693.html http://lists.altlinux.ru/pipermail/devel/2006-February/028693.html]
* [http://lists.altlinux.ru/pipermail/devel/2006-February/028695.html http://lists.altlinux.ru/pipermail/devel/2006-February/028695.html]

Версия от 09:19, 8 ноября 2008

Правила упаковки документации

Упаковке подлежит вся документация, поставляемая с программой/библиотекой, за исключением

  • стандартных файлов INSTALL, содержащих строку "These are generic installation instructions.". Эти файлы создаются путем копирования /usr/share/automake-*/INSTALL в процессе работы automake.
  • пустых файлов NEWS и т.д.
  • файлов стандартных лицензий
  • руководств по сборке/установке программы, содержащие тривиальные рекомендации про ./configure && make && make install
  • файлов вида ChangeLog, генерирующихся из системы контроля версий и содержащих просто список коммитов

Документация для разработчиков (описание API, примеры и т.д.) пакуется, в зависимости от размера

  • в -devel-пакет, если размер документации меньше остального содержимого пакета
  • в -doc (или -devel-doc, если в -doc находится документация для пользователей), в противном случае

Объёмные файлы Changelog и NEWS необходимо сжимать перед упаковкой. Сжатию подлежат файлы более 100 килобайт, а также файлы, сжатием которых достигается значительный выигрыш в размере бинарного либо установленного пакета.