Искусство программирования для Unix
Шрифт:
Написание документов с помощью DocBook (Writing Documents Using DocBook) <http: //xml .Web. cern.ch/XML/goossens/dbatcern/> — превосходное учебное пособие.
Существует также одинаково полезный список часто задаваемых вопросов (DocBook FAQ), <http://www.dpawson.co.uk/docbook/> с большим количеством материалов по форматированию HTML-вывода. Кроме того, функционирует ОосВоок-форум (DocBookwiki) <http: //docbook.org/wiki/moin. cgi>.
Наконец, в документе "The XML Cover Pages" chttp: / /xml. coverpages. org/> представлены описания XML-стандартов.
18.6. Лучшие практические приемы написания Unix-документации
Рекомендацию,
Не следует, однако, полагать, что объем является ошибкой с точки зрения качества. И что особенно важно — никогда не следует опускать функциональные детали, опасаясь, что они могут запутать читателя. Не стоит также опускать предупреждения об имеющихся проблемах, чтобы продукт не выглядел плохо. Именно неожиданные проблемы, а не проблемы, которые разработчик признает открыто, будут стоить ему доверия и пользователей.
Пытайтесь найти золотую середину при подаче информации. Слишком малая насыщенность так же неудачна, как и слишком большая. Расчетливо используйте снимки с экранов; часто они несут мало информации, выходящей за рамки восприятия пользовательского интерфейса, и никогда полностью не заменят хорошего текстового описания.
Если разрабатываемый проект имеет значительные размеры, следует, вероятно, поставлять документацию в трех видах: man-страницы в качестве справочного материала, учебный материал, а также список часто задаваемых вопросов (Frequently Asked Questions — FAQ). Также следует создать Web-сайт, который будет служить центральной точкой распространения продукта (основные принципы взаимодействия с другими разработчиками изложены в главе 19).
Большие man-страницы несколько раздражают пользователей; навигация в них может быть затруднена. Если man-страницы получаются большими, следует рассмотреть возможность написания справочного руководства, а в man-страницах предоставить краткое обобщение и указатели на справочный материал, а также подробности вызова программы (или программ).
В исходный код следует включать стандартные файлы метаинформации, такие как README, которые описаны в разделе главы 19, касающемся практических приемов выпуска программ с открытым исходным кодом. Даже если предполагается, что разрабатываемый код будет закрытым, эти файлы подчиняются соглашениям Unix и будущие кураторы, приходящие из Unix-среды, быстро вникнут в суть.
man-страницы должны быть авторитетными справочниками в традиционном Unix-стиле для обычной Unix-аудитории. Учебные пособия должны быть документацией в развернутой форме для нетехнических пользователей. FAQ-списки должны быть развивающимися ресурсами, которые растут по мере того, как группа поддержки программы выясняет часто задаваемые вопросы и ответы на них.
Существуют более специфические привычки, которые необходимо развить современному разработчику.
1. Поддержка главных документов в XML-DocBook. Даже man-страницы могут быть документами DocBook Ref Entry. Существует очень хорошее методическое руководство (HOWTO) <http://www.linux.doc.org/HOWTO/mini/ Man-Page. html> по созданию man-страниц, в котором описана общая организация, ожидаемая пользователями.
2. Поставка документации с главными XML-файлами. На случай, если системы пользователей не имеют xmlto(1), поставляйте
3. Создание БсгоПКеерег-совместимого инсталляционного пакета проекта.
4. Создание XHTML-документов из главных документов (с помощью команды xmlto xhtml) и предоставление к ним доступа с Web-страницы проекта.
Независимо от того используется ли в качестве главного формата XML-DocBook, необходимо найти способ конвертирования документации проекта в HTML. Независимо от того, как поставляется разрабатываемое программное обеспечение — как открытый исходный код или как частная программа, — растет вероятность того, что пользователи найдут ее посредством Web. Непосредственный эффект от размещения документации в Web-среде заключается в том, что это упрощает ее чтение и изучение для потенциальных пользователей и клиентов, знающих о существовании программы. Кроме того, возникает косвенный эффект — повышается вероятность появления программы в результатах Web-поиска.
19 Открытый исходный код: программирование в новом Unix-сообществе
Программы как секс — лучше, когда они бесплатны. —Линус Торвальдс
Глава 2 заканчивалась формулировкой самого значительного закона в истории Unix. Операционная система Unix "расцветала", когда ее практика наиболее близко приближалась к открытому исходному коду, и приходила в упадок, когда этого не было. Затем в главе 16 утверждалось, что инструменты разработки с открытым исходным кодом часто характеризуются высоким качеством исполнения. Данная глава начинается с общего объяснения того, как и почему действует разработка открытого исходного кода. Большая часть ее поведения является просто усилением общепринятых практических приемов в традиции Unix.
Затем дискуссия выходит из области абстракции, и описываются некоторые из наиболее важных народных традиций, которые Unix заимствовала из сообщества открытого исходного кода, особенно развившиеся в сообществе основные правила относительно того, как должен выглядеть хороший код. Многие из данных традиций могут быть также успешно заимствованы разработчиками в других современных операционных системах.
Данные традиции описываются в предположении, что читатели разрабатывают открытый исходный код. Большинство традиций представляют собой хорошие идеи даже при написании частного программного обеспечения. Предположение об открытом исходном коде является исторически целесообразным, поскольку многие из описываемых традиций через вездесущие инструменты с открытым исходным кодом, такие как patch(1), Emacs и GCC, "уходят корнями" в частные лаборатории разработки Unix.
19.1. Unix и открытый исходный код
В разработке открытого исходного кода используется тот факт, что выяснение и исправление ошибок, в отличие от, например, реализации определенного алгоритма, является задачей, которая допускает ее разделение на несколько параллельных подзадач. Исследование совокупности возможностей, связанных с конструкцией прототипа, также может осуществляться параллельно. При наличии верного технологического и социального аппарата весьма крупные коллективы разработчиков, которые тесно связаны сетью, способны выполнять поразительно хорошую работу.