Действительный Asciidoc для преобразования в Manpage (с a2x)

Я хочу написать справочную страницу для моего CLI-скрипта с помощью Asciidoc и преобразовать ее с помощью

a2x --doctype manpage --format manpage MYMANPAGE.ASCIIDOC

Я не смог найти ни одного примера Asciidoc, который можно было бы успешно преобразовать в справочную страницу с помощью этой команды. Не могли бы вы указать мне пример или предоставить один?


asciidoc manpage
person Wolkenarchitekt    schedule 10.07.2012    source источник

Ответы (2)


arrow_upward
6
arrow_downward

Нашел пример - из самих исходников Asciidoc:

http://code.google.com/p/asciidoc/source/browse/doc/asciidoc.1.txt

(Тем не менее, приветствуются дополнительные примеры для справочных страниц в формате Ascii-doc!)

person Wolkenarchitekt    schedule 10.07.2012
comment
Я использую asciidoc для своих справочных страниц: github.com/DavidGamba/grepp К сожалению, конвертер не поддерживает весь синтаксис asciidoc, поэтому я считаю необходимым разделить справочную страницу для командной строки и html-версии. - person DavidG; 29.10.2013

arrow_upward
1
arrow_downward

В дополнение к ссылке из ответа @ifischer, которая представляет собой очень полезный пример, я хотел бы направить читателей на следующую страницу из документации asciidoc: http://www.methods.co.nz/asciidoc/chunked/ch24.html.

В частности, упоминается, что:

  • заголовок должен быть правильно отформатирован (например: PROGRAM(1))

  • тип документа должен быть "manpage" (например: ":doctype: manpage")

  • первый раздел должен быть «Имя». Содержимое этого раздела также должно быть правильно отформатировано (например: «программа - ...»)

  • второй раздел должен быть «Синопсис». Похоже, содержимое этого раздела может быть любым, хотя стандартная практика man-страницы состоит в том, чтобы перечислить все параметры вызова программы.

  • Документ, конечно, должен быть правильно отформатированным документом asciidoc.

Существуют необязательные элементы информации, которые можно указать для справочной страницы с помощью ":directives:" в заголовке документа.

Когда вы запустите a2x, он автоматически присвоит выходной справочной странице имя на основе содержимого раздела имени и заголовка. Я считаю, что он всегда называется «name.x», где имя из раздела имен, а x — номер из заголовка.

person Matthew    schedule 08.01.2014