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


16

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

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

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

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

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


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

man man, man groff.
Дженни Д

Ответы:


13

6

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

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

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

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


"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 - хороший выбор

Используя наш сайт, вы подтверждаете, что прочитали и поняли нашу Политику в отношении файлов cookie и Политику конфиденциальности.
Licensed under cc by-sa 3.0 with attribution required.