- 6 Источники информации по Linux
- 6.1 Документы, доступные по он-лайн
- 6.2 Руководства проекта LDP (Linux Documentation Project)
- 6.3 Книги и другие публикации
- 6.3.1 Использование UNIX
- 6.3.2 Системное администрирование
- 6.3.3 The X Window System
- 6.3.4 Программирование
- 6.3.5 Kernel Hacking
- Linux howto что это
- Авторские права
6 Источники информации по Linux
Это приложение содержит информацию по различным источникам Linux, таким как документация, доступная по он-лайн, книги и другое. Многие из этих документов либо доступны в печатном виде, либо в электронном через Internet или BBS. Многие дистрибутивы Linux сами по себе также включают много документации, так что после инсталляции Linux эти файлы могут оказаться у вас в системе.
6.1 Документы, доступные по он-лайн
Эти документы должны быть доступны на любых FTP-серверах с архивами Linux (Смотри список в Приложении C). Если у вас нет прямого выхода по FTP, вы можете найти эти документы на других он-лайновых серверах (например, CompuServe, местные BBS и т.д.). Если у вас есть доступ к почте Internet, вы можете использовать сервис ftpmail для получения этих документов. Дополнительную информацию смотрите в Приложении C.
В частности, следующие документы могут быть найдены на sunsite.unc.edu в директории /pub/Linux/docs . Многие узлы имеют зеркальное отображение этого директория, однако, если у вас нет зеркального узла поблизости, можно связаться с названным ранее.
Вы можете также получить доступ к файлам Linux и документации с помощью gopher . Просто направьте вашего клиента gopher на порт 70 на sunsite.unc.edu и следуйте указаниям меню архива Linux . Это хороший способ интерактивного листания документации по Linux.
The Linux Frequently Asked Questions List или «FAQ» (Список Часто Задаваемых Вопросов) — это список наиболее типовых вопросов (и ответов!) по Linux. Этот документ обеспечивает общей информацией по Linux, описывает типовые проблемы и решения, перечисляет другие источники информации. Каждому новому пользователю Linux следует прочитать этот документ. Он доступен в различных форматах, включая «чистый» ASCII, PostScript, формат Lout. Linux FAQ сопровождается Ian Jackson, ijackson@nyx.cs.du.edu .
The META-FAQ подборка «матавопросов» по Linux; то есть про источники информации по Linux и другие вопросы общего характера. Это хорошее начало для абонента Internet, желающего получить больше информации о системе. Она сопровождается Michael K. Johnson, johnsonm@sunsite.unc.edu .
The Linux INFO-SHEET техническое введение в систему Linux. Дается обзор системных характеристик и доступных программ. Также приводится перечень других источников информации про систему Linux. Формат и содержание похожи на META-FAQ; случайно похож и сопровождающий: Michael K. Johnson johnsonm@sunsite.unc.edu .
The Linux Software Map — список многочисленных приложений, имеющихся для Linux; где их можно достать, кто их сопровождает и т.д. Он далек от полноты. — собрать полный список программ под Linux почти невозможно. Но этот список содержит большинство из наиболее популярных пакетов программ для Linux. Если вы не можете найти конкретные прикладные программы, удовлетворяющие ваши нужды, — хорошо начинать поиск с LSM. Он поддерживается Lars Wirzenius, lars.wirzenius@helsinki.fi .
The Linux HOWTO — собрание документов типа «как сделать», где каждый детально описывает конкретный аспект системы Linux. Он сопровождается Matt Welsh, mdw@sunsite.unc.edu . (прим. переводчика: т.е. автором данной книги, если кто потерял мысль). The HOWTO Index перечисляет доступные документы HOWTO (некоторые из которых приведены ниже).
The Linux Installation HOWTO описывает, как получить и инсталлировать Linux, похоже на информацию, представленную в Главе 2.
Этот документ представляет перечень дистрибутивов Linux, которые можно получить по почте и через anonymous FTP. Он также включает информацию о других связанных с Linux вещах и сервисе. Приложение B содержит список поставщиков Linux, многие из которых перечислены в Distribution HOWTO.
Этот документ описывает, как инсталлировать и настраивать X Window System для Linux. Смотрите Раздел «5.1» где X Window System рассмотрена более детально.
Эти три документа описывают конфигурацию и установку электронной почты, новостей и UUCP на системе Linux. Поскольку эти три вопроса тесно переплетаются, вы можете читать их вместе.
Этот документ содержит большой список аппаратуры, поддерживаемой Linux. Хотя этот список весьма далек от полноты, он может дать общее представление об аппаратуре, которая поддерживается системой.
The Linux SCSI HOWTO полное руководство по настройке и использованию SCSI-устройств под Linux, таких как диски, ленты и CD-ROM.
The Linux NET-2-HOWTO описывает инсталляцию, установку и настройку программ «NET-2» TCP/IP под Linux, включая SLIP. Если вы хотите использовать TCP/IP на вашей системе Linux, вы должны прочитать этот документ.
Документ тесно связан с NET-2-HOWTO. Ethernet HOWTO описывает различные устройства Ethernet, поддерживаемые Linux, и об’ясняет, как настраивать каждое из них при использовании Linux TCP/IP.
Этот документ описывает, как настраивать печатающие устройства под Linux, такие как lpr . Настройка принтеров и программ печати под UNIX временами может быть очень непростой; этот документ проливает некоторый свет на эту проблему.
Приведенный ниже список отражает текущее состояние документов по HOWTO. (прим. Переводчика: данный список отражает текущее состояние на момент перевода).
Другие документы он-лайн
Если вы просмотрите поддиректории с документами на любом Linux FTP-сервере, вы увидите много других документов, которые здесь не перечислены: множество FAQ, интересных новостей и другой важной информации. Эту россыпь трудно здесь классифицировать; если вы не найдете, что искали, посмотрите еще в архивах Linux серверов, перечисленных в Приложении С.
6.2 Руководства проекта LDP (Linux Documentation Project)
В рамках проекта The Linux Documentation Project (LDP) существует и разрабатывается множество руководств и другой документации для Linux, включая Руководство (информация, содержащаяся в команде «man»). Эти руководства находятся в различной стадии готовности и мы с благодарностью принимаем любую помощь по их правке, обновлению, совершенствованию. Если у вас есть вопросы по поводу LDP, пожалуйста свяжитесь с Matt Welsh mdw@sunsite.unc.edu .
Эту книгу на английском языке можно получить через anonymous FTP из многих архивов Linux, включая sunsite.unc.edu в директории /pub/Linux/docs/LDP . Ряд дистрибуторов продает печатные копии этой книги. В будущем вы сможете найти руководства LDP на полках ваших книжных магазинов. (прим. переводчика: за рубежом, в той же Америке, это будущее уже давно наступило).
Новое руководство пользователя по Linux, содержащее всю необходимую информацию для начала работы. Может так случиться, что вы держите эту книгу в руках.
Это полное руководство по эксплуатации и настройке системы Linux. Существует много специфических для Linux особенностей в работе Администратора системы, таких как поддержка сообщества пользователей, сопровождение файловой системы, резервирование системы и другое. Все это обсуждается в данном руководстве.
Подробное и полное руководство по сетевой работе под Linux, включая TCP/IP, UUCP, SLIP и т.п. Эта книга — очень хорошее чтение. Она содержит много ценной информации по многим аспектам, проясняет многие сложные вопросы настройки и эксплуатауции сети.
Интересные детали относительно ядра и разработок под Linux. Linux уникален тем, что доступны все исходные тексты ядра. Эта книга открывает двери разработчикам, которые желали бы заняться расширением и модификацией ядра. Это руководство также содержит понятное описание концепций ядра и используемых в Linux соглашений.
Приведенные ниже документы входят в проект LDP на момент перевода
6.3 Книги и другие публикации
Linux Journal — ежемесячный журнал для и про сплотившееся вокруг Linux сообщество, который наполняют и выпускают разработчики и энтузиасты Linux. Он распространяется по всему миру и является хорошим средством поддержания непосредственного контакта с динамическим миром Linux, особенно если у вас нет выхода в USENET.
В момент написания этой книги подписка на Linux Journal стоила $19 в год в США, $24 в Канаде и US$29 в остальном мире. По поводу подписки или для получения дополнительной информации пишите в Linux Journal, PO Box 85867, Seattle, WA, 98145-1867, USA, или звоните +1 206 527-3385. Номер их факса +1 206 527-2806, и e-mail linux@ssc.com. Вы можете также найти Linux Journal FAQ и некоторые статьи через anonymous FTP на sunsite.unc.edu в /pub/Linux/docs/linux-journal .
Как мы уже говорили, мало книг было опубликовано непосредственно по Linux. Так что, если вы новичок в мире UNIX или хотите получить дополнительную информацию, кроме представленной здесь, мы рекомендуем посмотреть следующие доступные книги.
6.3.1 Использование UNIX
Хорошая книга для начинающего изучать операционную систему UNIX. Большая часть информации может быть применена также к Linux. Я рекомендую эту книгу тем, кто является новичком и действительно желает начать пользоваться этой новой для него системой.
Эта книга о редакторе vi — мощном текстовом редакторе, который можно найти на любой системе UNIX мира. Часто бывает важно знать и быть готовым применить vi, поскольку не всегда вы будете иметь доступ к «настоящим» редакторам, вроде Emacs.
6.3.2 Системное администрирование
Из каталога O’Reilly and Associates: «Как любая другая многопользовательская система, UNIX требует определенной заботы и внимания. Essential System Administration и рассказывает как это надо делать. Эта книга развеивает миф и замешательство вокруг этого вопрос; дает краткое информативное введение в задачи, с которыми сталкивается любой, отвечающий за эксплуатацию системы UNIX». Я лучше этого сформулировать не могу.
Полное руководство по установке и эксплуатации TCP/IP. Хотя эта книга не посвящена непосредственно Linux, приблизительно 90% ее применимо к Linux. Совместно с Linux NET-2-HOWTO и Linux Network Administrator’s Guide это замечательная книга, обсуждающая соответствующие концепции и детали работы с TCP/IP.
Эта книга рассматривает вопросы, как инсталлировать и настраивать сетевые программы UUCP, включая настройку на работу с новостями USENET. Если вас интересует использование UUCP или доступ к новостям USENET, вам следует прочитать эту книгу.
6.3.3 The X Window System
Полное учебное пособие и справочник по использованию X Window System. Если вы инсталлируете X windows на вашем Linux и хотите знать, как извлечь из этого максимум, вам стоит прочитать эту книгу. В отличие от других оконных систем, многие возможности, которые дает X не видны с первого взгляда.
6.3.4 Программирование
Эту книгу следует иметь обязательно любому, пожелавшему программировать на C в ОС UNIX. (Или в другой системе из этой обоймы). Хотя эта книга не ограничивается лишь UNIX, она вполне применима к программированию на C в UNIX.
Обзор программирования в UNIX. Рассматриваются все инструменты; хорошее чтение для желающих познакомиться с аморфным миром UNIX.
Это мощный том, содержащий все, что вам необходимо знать для программирования на системном уровне UNIX — ввод-вывод файлов, процессы, управление, взаимодействие процессов, сигналы, работа с терминалом. Эта книга делает акцент на различных стандартах UNIX, включая POSIX.1, который в значительной степени выдерживается в Linux.
6.3.5 Kernel Hacking
Эта книга рассматривает алгоритмы и внутренние механизмы ядра UNIX. Она не привязана к какому-то конкретно ядру, хотя больше тяготеет к System V-isms. Это лучшее, с чего можно начать, если хотите понять, что и как «тикает» внутри системы Linux.
Эта книга детально описывает ядро System V R4. В отличие от книги Bach-а, которая прежде всего сосредотачивается на алгоритмах, которые «тикают» в ядре, эта книга представляет реализацию SVR4 на более техническом уровне. Хотя Linux и SVR4 дальние родственники, эта книга может дать представление о действительной работе реального ядра UNIX. Кроме того, это достаточно свежая книга, посвященная ядру UNIX — издана в 1994.
Источник
Linux howto что это
Copyright 1995-2000 by Jens Schweikhardt, email:
Информацию относительно условий копирования ищите ниже.
Последнее обновление: Июль 2000. Щелкните здесь, чтобы просмотреть последнюю версию этого документа. Исправления и комментарии приветствуются!
Этот HOWTO разъясняет вам, что вы должны иметь в виду, если вы собираетесь составить страницы руководства (man pages), которые вы хотите сделать доступными по команде man. В этом HOWTO, слово «руководство» понимается в качестве страниц руководства.
0) Некоторые мысли по поводу документации
Почему мы пишем документации? Глупый вопрос. Мы хотим, чтобы другим было понятно, как использовать нашу программу, библиотечную функцию или что-то еще, написанное или сделанное. Но написание документации — это еще не все. Необходимо, чтобы:
- документация была доступна. Если она скрыта в каком-то нестандартном месте, то специальные программы не смогут найти ее — каким образом тогда ее использовать?
- документация была точная и аккуратная. Нет ничего более раздражающего, чем несогласованность документации и программы. Если это будет иметь место, то пользователи проклянут вас, будут слать гневные письма и выбросят вашу программу и документацию, с твердым намерением никогда не устанавливать что-либо, написанное вами.
Исторически заведено и всем известно, что документация доступна по команде man(1). Этот HOWTO разъясняет, как вам написать руководство, которое будет корректно обрабатываться утилитами для просмотра документации. Наиболее известные из этих утилит — man(1), xman(1x), apropos(1), makewhatis(8) и catman(8). Точность и аккуратность информации зависит, конечно, только от вас. Но даже в этом отношении вы найдете некоторые идеи, которые помогут избежать некоторых общих ошибок.
1) Как дать имя руководству, и где его установить?
Вам необходимо знать точный механизм, как дать правильное имя руководству и где его правильно установить. Любое руководство должно находиться в определенном разделе, который обозначается определенным символом. Общие разделы под Linux и их описания:
Имя исходного файла руководства состоит из имени команды, функции или файла, дальше сиавится точка и имя раздела. Если вы пишете документацию по формату файла ‘passwd’, вы должны дать имя исходному файлу — ‘passwd.5’. Здесь пример имени файла, совпадает с названием команды. Представим, что может существовать библитечная функция ‘passwd’. Секционирование — обычный способ разрешить противоречия: Описание команды будет найдено в файле ‘passwd.1’, а описание выдуманной библиотеки — в файле ‘passwd.3’.
Иногда в конце имени файла добавляются дополнительные символы, и имя файла выглядит, например, так: ‘xterm.1x’ или так ‘wish.1tk’. Это намеренно сделано для того, чтобы показать, что эта документация для программ X Window program или для приложений Tk, соответственно. Некоторые программы для просмотра страниц руководства могут использовать эту дополнительную информацию. Например, xman будет использовать ‘xterm(x)’ и ‘wish(tk)’ в списке доступной документации.
Пожалуйста, не используйте разделы n, o и l; согласно стандарту файловой системы эти разделы не одобряются. Используйте номера разделов. Остерегайтесь совпадения имен с существующими программами, функциями или именами файлов. Это конечно плохая идея — написать редактор и назвать его ed, sed («умный» ed) или red (Rocky ed). Удостоверьтесь, что имя вашей программы уникально, тем самым вы избежите того, что кто-то ненарочно выполнит вашу программу или прочитает не то руководство. Проверьте базу данных lsm программ перед тем, как назвать свое творение.
Теперь мы знаем имя нашего файла. Следующее — мы должны решить, в какой каталог установить программу (скажем, когда пользователь запустит команду ‘make install’ для вашего пакета) на Linux, все руководства устанавливаются в каталоги, упомянутые в переменной MANPATH. Утилиты для работы с документациями используют ее, как shell использует PATH для выполнения программ. Фактическиt, MANPATH имеет тот же формат, что и PATH. Обе переменные содержат список каталогов, разделенных двоеточием, «:» (с тем исключением, что MANPATH не содержит пустых полей и относительных путей, и имеет только абсолютные пути). Если MANPATH не установлена или не экспортируется, по умолчанию будет использоваться содержимое каталога /usr/man. Для ускорения поиска в каталогах, определенных в MANPATH (называемые основными каталогами) содержат связку подкаталогов, названных ‘man‘, где — замещает символ (указан выше в таблице). Не все разделы могут быть представлены каталогом, потому что нет никаких причин хранить пустой каталог ‘mano’. Однако могут быть каталоги, названые ‘cat‘, ‘dvi‘ и ‘ps‘, которые содержат документацию, готовую для печати или вывода на экран. Об этом позже. Единственный файл, который должен быть в каталоге — файл называемый ‘whatis’. Цели и создание этого файла будет описано в параграфе 11). Самый безопасный способ иметь страницы руководства для раздела — установка их в правильном месте — в каталоге /usr/man/man. Хороший Makefile, однако, позволит пользователю выбрать основной каталог, в зависимости от значения переменной MANDIR. Большинство пакетов могут быть настроены с опцией —prefix=/what/ever. Страницы руководства будут устанавливаться в основной каталог /what/ever/man. Постарайтесь обеспечить возможность подобного выбора.
С появлением Linux File System Standard (FS-Stnd), вещи стали более сложными. FS-Stnd 1.2 говорит, что:
«Для поддержки страниц руководства, написанных на разных языках, соответствующие условия должны быть созданы в самой структуре /usr/man.»
Это достигнуто благодаря тому, что были введены уровни каталогов, для различных языков. Цитата из FS-Stnd 1.2:
«Названия каталогов для различных языков в /usr/man основаны на Приложении E (POSIX 1003.1), по стандарту которого описывается строка идентификации для языков. Строка : [_ ][. ][, ]»
(Смотрите FS-Stnd для некоторых общих строк .) Согласно этим принципам, наши страницы руководства имеются в каталогах /usr/man/ /man[1-9lno]. Форматированные версии должны быть в /usr/man/ /cat[1-9lno], иначе вы сможете обеспечить их только для единственного языка. ОДНАКО, я не рекомендую прямо сейчас следовать этой структуре. FS-Stnd 1.2 также позволяет это
«Система, которая использует уникальный язык или кодовую страницу для всех руководств может пропускать подстроку и хранить все руководства в каталоге . Например, система, в которой используется только английские страницы руководства в ASCII коде, могут хранить страницы руководства (каталоги man1) прямо в /usr/man. (Фактически это традиционное местоположение.)»
Я не думаю, что все утилиты (типа xman, tkman, info и многие другие, которые читают руководство) могут справляться с новой структурой.
2) Как должно выглядеть отформатированное руководство?
Позвольте мне привести вам пример. Ниже я объясню его подробнее. Если вы читаете этот документ, как простой текст вам не будут показаны различные шрифты (жирный и наклонный). Пожалуйста, обратитесь к параграфу «Какие существуют соглашения по шрифтам?» для дальнейших объяснений. Здесь приведено руководство по гипотетической программе foo .
Здесь пойдут объяснения, как я и обещал.
Раздел NAME (НАЗВАНИЕ)
. является единственным обязательным полем. Руководства без раздела name также бесполезны, как холодильник на северном полюсе. Этот раздел имеет стандартизированный формат, представляющий собой список программ или функции, разделенных запятыми и через тире идет короткое описание возможностей программы или функций. Посредством makewhatis(8) содержимое раздела name попадет в файл базы данных whatis. Makewhatis является причиной, почему должен существовать раздел name и почему мы должны придерживаться описанного формата. В исходном тексте мы увидим следующее
.SH NAME foo \- frobnicate the bar library
\- имеет здесь значение. Обратная косая черта нужна, чтобы показать, что она отлична от дефиса, который может появляться в названии команды или в строке описания.
Раздел SYNOPSIS (СИНТАКСИС)
. предназначен, чтобы дать краткий обзор доступных опций программы. Для функций он делит на части два списка: подключаемые файлы и прототипы функций, т.о. программист знает число и типы параметров, а также тип возвращаемого значения.
Раздел DESCRIPTION (ОПИСАНИЕ)
. дает доступное объяснение возможностей программы или функций. Здесь вы выкладываете все ваши знания. Приложите все ваши умения, для того, чтобы добиться восхищения других, сделав этот раздел надежным и детальным источником информации. Объясните: какие используются аргументы, формат файла, алгоритмы и т.п.
Раздел OPTIONS (ОПЦИИ)
. содержит описание для всех опций, которые влияют на работу программы. Вы знали их, не так ли?
Раздел FILES (ФАЙЛЫ)
. список используемых программ и функций. Например, файлы настройки, автозагружаемые файлы, файлы с которыми непосредственно работает программа. Лучше использовать полные пути к этим файлам и заставить make изменить пути, если пользователь предпочтет другое местоположение для программы: для groff по умолчанию заданный префикс — /usr/local, т.о., они ссылаются на /usr/local/lib/groff/*. Однако, если вы установите ‘make prefix=/opt/gnu’, тогда ссылка в руководстве изменится на /opt/gnu/lib/groff/*
Раздел ENVIRONMENT (СРЕДА)
. список всех переменных окружения, которые влияют на вашу программу или функцию. Обычно переменные содержат пути, имена файлов или опции по умолчанию.
Раздел DIAGNOSTICS (ДИАГНОСТИКА)
. должен дать описание большинству выдаваемых вашей программой сообщений об ошибках и способы их исправления. Нет никакой необходимости объяснять сообщения о системных ошибках (от perror(3)) или фатальные ошибки (от psignal(3)), поскольку они могут появляться при работе любых программ.
Раздел BUGS (ОШИБКИ)
. в идеале его не должно быть. Если у вас хватит смелости, вы можете описать здесь ограничения, известные неудобства в работе с программой, особенности, которые другие могут расценивать их как ошибки. Если вы не так смелы, тогда переименуйте ее в раздел TO DO 😉
Раздел AUTHOR (АВТОР)
. хорош в том случае, когда вы хотите получать сообщения об ошибках в документации или в программе.
Раздел SEE ALSO (СМ. ТАКЖЕ)
. список (в алфавитном порядке) руководств, которые могут быть связаны с вашим руководством. Традиционно — это последний раздел.
Вы можете вставить свои разделы, если они действительно не соответствуют одному из описанных разделов. Так как же точно выглядит руководство? Я ожидал этот вопрос, здесь вы можете посмотреть источник:
3) Как задокументировать несколько программ/функций на одной странице руководства?
Многие программы (grep, egrep) и функции (printf, fprintf, . ) описываются в одном руководстве. Однако, эти страницы были бы почти бесполезны, если они были доступны только под одним названием. Мы не вправе ожидать, что пользователь помнит, что руководство по egrep — это фактически руководство по grep. Поэтому необходимо иметь руководство доступное под различными именами. Есть несколько способов достичь этого:
- иметь одинаковые копии для каждого имени.
- связать все руководства жесткими ссылками.
- использовать символьные ссылки на фактическое руководство.
- использовать механизм groff обеспеченный макросом ‘.so’.
Первый способ — трата дискового пространства. Второй способ не рекомендуется, потому что интеллектуальные версии программы catman могут сохранять работу в зависимости от типа и содержания файла. Жесткие ссылки препятствуют программе catman. (цель catman состоит в том, чтобы отформатировать все руководства так, чтобы они как можно быстрее отображались на экране.) Третья альтернатива имеет небольшой недостаток: вы должны знать, что существуют файловые системы, которые не поддерживаю символьные ссылки. В результате этого — Лучшая Вещь (TM) — использовать механизм groff. Здесь скажу о том, как это сделать: Если вы хотите видеть страницы руководства доступными под именами ‘foo’ и ‘bar’ в разделе 1, тогда поместите руководство в файл foo.1 и сделайте файл bar.1 такого типа:
Важно определить директивную часть ‘man1/’ также, как имя файла ‘foo.1’, потому что когда groff будет запущен браузером, он будет иметь базовым каталогом текущий рабочий каталог (трк), а groff интерпретирует аргументы относительно трк.
4) Какой макропакет использовать?
Существует множество макропакетов, специально предназначенных для использования при написании руководств. Обычно они находятся в каталоге макросов groff /usr/lib/groff/tmac. Имена файлов tmac. , где — аргумент опции -m для groff. Groff будет использовать tmac. , когда он работает с опцией ‘ -m ‘. Часто пробел между ‘ -m ‘ и ‘ ‘ опускается, и тогда может получиться ‘ groff -man ‘, когда мы форматируем руководства, используя макрос tmac.an . По этой причине дано странное название ‘tmac.an’. Кроме того, имеется другой популярный макрос — tmac.doc , который сделан в калифорнийском университете Беркли (UCB). Большинство руководств BSD используют его, и он, кажется, сделан (в UCB) стандартным для документаций. Макрос tmac.doc более гибок, но, увы, браузеры для руководств не используют его и всегда вызывают groff -man . Например, все программы xman , я видел, требуют tmac.doc . Т.о., для вашей пользы: используйте tmac.an — использование любого другого макропакета нежелательно. tmac.andoc — псевдомакрос, который просматривает источник и затем загружает либо tmac.an , либо tmac.doc . Фактически, любой браузер руководств должен его использовать, но до сих пор не все это делают, т.е., лучше использовать старый tmac.an . Если, так или иначе, вы хотите использовать макрос tmac.doc , здесь имеется более детальное описание, объясняющее, как им пользоваться: http://www.bsdi.com/bsdi-man . На странице имеется форма для поиска. Введите mdoc.samples, и вам будет найден mdoc.samples(7) — обучающий пример по написанию страниц руководства для BSD.
Описание для troff (Troff User’s Manual), со всеми объясненными макросами, доступно в html , PostScript (ps, 760K) или в Portable Document Format (pdf, 240K) . AT&T Bell Labs сделали его общедоступным. Не забудьте проверить домашнюю страницу W. Richard Steven (известный по книге Unix Network Programming, а также по трилогии TCP/IP Illustrated), который также имеет список ресурсов по Troff Resources , включающий tbl, eqn, pic и др.
5) Какие препроцессоры я могу использовать?
Groff идет, с минимум, тремя препроцессорами — tbl, eqn, и pic (на некоторых системах они называются — gtbl, geqn и gpic). Их цель — транслировать макрокоманды препроцессора и данные для troff. Tbl — табличный препроцессор, eqn — препроцессор для выражений и pic — препроцессор изображений. Пожалуйста, обратитесь к руководству, за более детальной информацией и описанием возможностей, которые они обеспечивают. Чтобы обезопасить себя: не пишите руководства, требующие ЛЮБЫЕ препроцессоры. Eqn будет вообще делать ужасный вывод для текстовых устройств, к сожалению, в 99% случаев руководства просматриваются на таких устройствах. Например, XAllocColor.3x использует несколько формул с экспонентами. Из-за характера таких устройств, экспонента будет на той же самой строке, что и основание. N в квадрате — ‘N2’. Tbl необходимо избегать, потомучто все программы xman, которые я видел, сбоили с ним. Xman 3.1.6 использует следующие команды для форматирования руководств, напр. signal(7):
gtbl /usr/man/man7/signal.7 | geqn | gtbl | groff -Tascii -man /tmp/xmana01760 2> /dev/null
которые разворачивают источник, используя gtbl, gtbl выводит снова в gtbl. В результате получается руководство без вашей таблицы. Я не знаю — это ошибка или особенность, что gtbl подавляет свой собственный вывод или если бы xman был бы «умнее», он не использовал бы gtbl дважды. Так или иначе, если вы хотите иметь таблицу, форматируйте ее непосредственно в тексте и поместите между строками .nf и .fi, чтобы к ней не применялось форматирование. У вас не будет жирного шрифта или курсива при использовании этого способа, но он позволит вам получить таблицу. Я должен все-таки увидеть руководство, использующее препроцессор pic. Но я не хотел бы этого.
6) Как я должен распространять готовое руководство?
Позвольте мне собрать доводы за (+) и против (-) из нескольких отобранных возможностей:
- Только источник:
+ небольшой дистрибутивный пакет.
— недоступно на системах без groff. - Несжатое и форматированное:
+ доступно даже на системах без groff.
— пользователь не может сгенерировать файлы dvi или postscript.
— трата дискового пространства. - Сжатое и форматированное:
+ доступно даже на системах без groff.
— пользователь не может сгенерировать файлы dvi или postscript.
— который формат сжатия вы бы использовали? .Z? .z? .gz? Все из них? - Источник и несжатый и форматированный:
+ доступно даже на системах без groff.
— большой дистрибутивный пакет.
— некоторые системы ожидают сжатые отформатированные руководства.
— избыточная информация для систем с groff.
IMHO лучше всего распространять только источник. Аргумент, что он не будет доступен на системах без groff, не имеет значения. Более 500 руководств Linux Documentation Project в виде исходных текстов. Руководства для XFree86 содержатся в виде исходных текстов. Руководства от FSF идут только в виде источника. Фактически, я редко видел дистрибутивы, распространяемые с отформатированными страницами руководства. Если какой-то сисадмин заинтерисован в руководстве, то он сам установит groff.
7) Какие существуют соглашения по шрифтам?
Прежде всего: не используйте напрямую операторы типа \fB \fP и т.п. Используйте макросы, которые принимают аргументы. Таким способом вы избежите обычного сбоя: забыть сменить типа шрифта в конце слова и при наличии других шрифтов продлевает их использование до следующей смены шрифта. Поверьте мне, это случается чаще, чем многие думают. Макрос tmac.an обеспечивает следующие типы шрифтов:
.BI Жирный чередуется с наклонным
.BR Жирный чередуется с Roman
.IB Наклонный чередуется сжирным
.IR Наклонный чередуется с Roman
.RB Roman чередуется с жирным
.RI Roman чередуется с наклонным
.SM Малый (9/10 от нормального размера)
.SB Малый чередуется с жирным
X чередуется с Y, в этом случае, нечетные параметра набраны шрифтом X, а четный — шрифтом Y. Например:
.BI «Arg 1 — жирный, » «Arg 2 — наклонный, » «и жирный, » «и наклонный.»
Двойные кавычки необходимы, чтобы включить пробелы в аргументы; без них не будет пробелов между чередующимися шрифтами. Фактически, вам будут нужны только макросы для чередующихся шрифтов для того, чтобы при смене шрифта не было незаполненого пространства. Ниже описано то, как использовать различные шрифты: (часть взято из man(7))
Хотя имеется множество разных соглашений для руководств в мире UNIX, существуют сотни руководств для Linux определяющие наши стандарты: для функций, аргументы всегда записаны наклонным шрифтом, даже в разделе SYNOPSIS, где остальная часть функции выводится жирным шрифтом:
.BI «myfunction(int » argc «, char **» argv );
Имена файлов всегда выводятся наклонным шрифтом, исключая раздел SYNOPSIS, где для них используется жирный шрифт. Т.е., вы должны использовать:
Специальные макросы, которые обычно записываются в верхнем регистре, выводятся жирным шрифтом:
В списке кодов ошибок: коды выводятся жирным шрифтом. Этот список обычно использует .TP (параграф):
.TP
.B EBADF
.I fd is not a valid file descriptor.
.TP
.B EINVAL
.I fd is unsuitable for reading
Любые ссылки на другие руководства (или на другие темы в данном руководстве) выводятся жирным шрифтом. Если дается номер раздела, то он выводится шрифтом roman:
Акронимы смотрятся лучше всего, когда набраны мелким шрифтом. Т.е., я рекомендую:
8) Как мне сделать руководство безупречным?
Ниже даны некоторые правила, которые обеспечивают надежность, удобочитаемость и «форматируемость» вашей документации.
- Сделайте проверку орфографии.
- Протестируйте ваше руководство: Выдает ли groff ошибки, когда форматирует ваше руководство? Желательно иметь команду groff в коментариях. Выдает ли команда man(1) ошибки, когда вы вызываете ‘man ваша_программа’? Правильно ли выглядит отформатированная страница? Работают ли xman(1x) и tkman(1tk) с вашим руководством? XFree86 3.1 имеет xman 3.1.6 — X11R6, он будет пробовать использовать несжатое руководство
gzip -c -d %s
zcat %s - Способен ли makewhatis(8) извлекать описание из раздела NAME?
9) Как получить простое текстовое руководство, без лишних элементов?
Взгляните на col (1), col способен отфильтровывать экранирующие последовательности. Проверьте:
funnyprompt$ groff -t -e -mandoc -Tascii manpage.1 | col -bx > manpage.txt
Ключи -t и -e сообщают groff об использовании препроцессоров tbl и eqn. В этом случае будет немного задерживаться вывод для страниц, которым не требуется такая обработка. С другой стороны, отказ от использования -t, когда это требуется, вредит: таблицы будут неправильно отформатированы. Вы можете даже выяснить, какая команда необходима для форматирования страницы:
funnyprompt$ grog /usr/man/man7/signal.7 groff -t -man /usr/man/man7/signal.7
«Grog» замещает «GROff Guess», и делает то, что говорит guess. В этой работе я привожу небольшой скрипт на perl, который удаляет верхние и нижние колонтитулы. Сохраните его под именем strip-headers и выполните chmod 755.
Используйте скрипт в качестве первого фильтра после команды ‘man’, поскольку он обрабатывает то, что выводится после groff. Например:
funnyprompt$ man bash | strip-headers | col -bx > bash.txt
10) Как получить руководство в формате PostScript?
funnyprompt$ groff -t -e -mandoc -Tps manpage.1 > manpage.ps
Отпечатайте или просмотрите это руководство, используя ваш любимый принтер/просмотрщик PostScript. См. вопрос 9) для уточнения опций.
11) Как заставить работать ‘apropos’ и ‘whatis’?
Предположим, что вы задались вопросом — какие компиляторы установлены на вашей системе, и как они могут быть вызваны. Чтобы ответить на первый вопрос, выполните команду:
funnyprompt$ apropos compiler
f77 (1) — Fortran 77 compiler
gcc (1) — GNU C and C++ compiler
pc (1) — Pascal compiler
Apropos и whatis используются, чтобы дать быстрый ответ, на который имеется информация в руководствах. Обе программы отыскивают файлы, называемые ‘whatis’, которые могут находиться в любом основном каталоге руководств. Прежде я говорил, файлы whatis содержат строки в каждой из которых содержится запись для любой страницы руководства из соответствующего каталога. Фактически, эта строка берется из раздела NAME (буду точнее: все строки раздела соединены в одну строку, также записано обозначение раздела в круглых скобках после имени руководства). Файлы whatis созданы с помощью программы makewhatis(8). Имеются разные версии программы, поэтому посмотрите руководства для уточнения доступных опций этой программы. Для makewhatis, способного извлекать информацию из раздела NAME, важно, чтобы вы правильно записывали информацию в этот раздел, твердо придерживаясь формата этого раздела, описанного в вопросе 2). Существуют различия между apropos и whatis. Apropos (эквивалентен man -k ) занимается поиском запроса в любой части строки, а whatis ( man -f ) ищет только целое слово. Следовательно, ‘ whatis cc ‘ сообщит есть ли руководство по cc и ничего не скажет о gcc.
Исправления и комментарии приветствуются!
A) Copying conditions
Copyright 1995-2000 by Jens Schweikhardt
Voice: ++49 7151 909516
Unless otherwise stated, Linux HOWTO documents are copyrighted by their respective authors. Linux HOWTO documents may be reproduced and distributed in whole or in part, in any medium physical or electronic, as long as this copyright notice is retained on all copies. Commercial redistribution is allowed and encouraged; however, the author would like to be notified of any such distributions. All translations, derivative works, or aggregate works incorporating any Linux HOWTO documents must be covered under this copyright notice. That is, you may not produce a derivative work from a HOWTO and impose additional restrictions on its distribution. Exceptions to these rules may be granted under certain conditions; please contact the Linux HOWTO coordinator at the address given below. In short, we wish to promote dissemination of this information through as many channels as possible. However, we do wish to retain copyright on the HOWTO documents, and would like to be notified of any plans to redistribute the HOWTOs. If you have questions, please contact the Linux HOWTO coordinator, Tim Bynum, at linux-howto@sunsite.unc.edu via email.
Авторские права
Авторские права на русский перевод этого текста принадлежат © 2000 SWSoft Pte Ltd. Все права зарезервированы.
Этот документ является частью проекта Linux HOWTO.
Авторские права на документы Linux HOWTO принадлежат их авторам, если явно не указано иное. Документы Linux HOWTO, а также их переводы, могут быть воспроизведены и распространены полностью или частично на любом носителе физическом или электронном, при условии сохранения этой заметки об авторских правах на всех копиях. Коммерческое распространение разрешается и поощряется; но так или иначе автор текста и автор перевода желали бы знать о таких дистрибутивах.
Все переводы и производные работы, выполненные по документам Linux HOWTO должны сопровождаться этой заметкой об авторских правах. Это делается в целях предотвращения случаев наложения дополнительных ограничений на распространение документов HOWTO. Исключения могут составить случаи получения специального разрешения у координатора Linux HOWTO с которым можно связаться по адресу приведенному ниже.
Мы бы хотели распространить эту информацию по всем возможным каналам. Но при этом сохранить авторские права и быть уведомленными о всех планах распространения HOWTO. Если у вас возникли вопросы, пожалуйста, обратитесь к координатору проекта Linux HOWTO по электронной почте: , или к координатору русского перевода Linux HOWTO компании SWSoft Pte Ltd. по адресу
Источник