Как я пишу справочные страницы? [закрыто]

16

Как мне написать справочную страницу?

Где я могу найти ссылку на все коды форматирования?

Есть ли хорошие руководства по написанию man-страниц?

Какой самый удобный способ написать справочную страницу? Должен ли я ввести его непосредственно в текстовом редакторе? Есть ли WYSIWYG редакторы? Или я должен написать это в другом формате и затем преобразовать?

Каким правилам должна следовать хорошая справочная страница?

documentation

— amarillion
источник

Этот вопрос представляется слишком широким. Ему удалось привлечь только несколько ссылок и только несколько неподдерживаемых мнений.

— 200_успех

man man, man groff.

— Дженни Д

13

Вот несколько веб-страниц, которые помогут вам начать:

Пара полезных инструментов:

— Приостановлено до дальнейшего уведомления.
источник

6

Существуют инструменты для написания man-страниц, которые обходят форматирование troff. manpages - это небольшой, хорошо разграниченный язык, на который легко ориентироваться.

Два популярных инструмента:

xmltoman , небольшой и хорошо структурированный язык xml, который может генерировать manpages и html. Он используется проектами Леннарта Поеттеринга, например , syrep и pulseaudio .
asciidoc , используемый git например .

yodl и zoem, кажется, другие хорошие форматы в этом пространстве.

В общем, я бы порекомендовал xmltoman, потому что это очень специфичный для man-страницы dsl, который будет вам очень близко.

— Tobu
источник

"dsl" == "специфичный для домена язык"?

— Приостановлено до дальнейшего уведомления.

да (да. си. 15 символов)

— Тобу

1

Другим хорошим вариантом является ronn , который читает более широко используемый язык разметки текста Markdown.

— пул

5

Я написал довольно обширную статью в блоге на эту тему, которую вы можете найти здесь:

http://2buntu.com/articles/1034/how-to-write-a-manpage/

— Натан Осман
источник

4

Было бы полезно, если бы вы хотя бы суммировали статью здесь - одни ссылки бесполезны, когда связанная страница неизбежно перемещается или исчезает.

— Калеб

Я не согласен с Калебом. Это сеть. Сеть основана на ссылках, и stackexchange не несет в себе никаких особых исключений. Копирование контента контрпродуктивно. Все, что может случиться с этой страницей или документом, может случиться и с этой страницей . Мы не можем копировать очищенные копии всего контента только потому, что остальная часть сети может исчезнуть. (Оставьте эту работу таким сайтам, как машина обратного хода).

— Каз

Каз, ты можешь не согласиться, но комментарий Калеба определенно является наилучшей практикой ServerFault.

— MadHatter

2

Я не знаю ни IDE, ни руководств, но вы можете начать с копирования существующей справочной страницы и изменить ее в соответствии со своими потребностями.

Для справки по языку groff с макросами MAN (который используется страницей man) обратитесь к странице man groff_man или прочитайте ее онлайн здесь

— Дэн Андреатта
источник

2

Взгляните на проект Ронна . Это уценка для генератора страниц man. Он также может генерировать справочные страницы в формате HTML, как это .

Мне нравится идея написать всю мою программную документацию в одном формате. Markdown IMO - хороший выбор

— Бруно Полако
источник