Perl 6 Pod: спецификаторы примеров

Pod предоставляет коды форматирования для указания примеров ввода, вывода, кода и мета синтаксиса:

  • Код T<> предназначен для указания терминального вывода, т.е. текста выводимого программой. Данный текст отображается шрифтом фиксированной ширины или обрамляется тэгами < <samp>...</samp> >. Содержимое кода T<> всегда обрабатывается с сохранением пробелов ( как если бы текст был обрамлен кодом S<...> ). Код T<> является строковым эквивалентом блока =output.

  • Код форматирования K<> указывает, что содержащийся внутри него текст, является клавиатурным вводом, т.е. некая последовательность, введенная пользователем. Такой текст отображается шрифтом фиксированной ширины ( предпочтительно отличным от используемого для T<>) или выделяется тэгами < <kbd>...</kbd> >. Содержимое кода K<> всегда выводится с неразрывными пробелами. K<> является строковым эквивалентом блока =input.

  • Содержимое кода C<> интерпретируется как программный код, т.е. текст, который может быть частью программы или спецификации. Данный текст обычно отображается шрифтом фиксированной ширины (желательно отличным от шрифтов кодов T<> или K<> ) или обрамляется тэгами < <code>...</code> >. Содержимое кода C<> транслируется в дословный (verbatim) текст с неразрывными пробелами. Код C<> является строковым эквивалентом блока =code.

    Чтобы использовать коды форматирования внутри C<>, используется предварительное конфигурирование:

    B<=config C<> :allow<E I>> Perl 6 makes extensive use of the B<E<laquo>> and B<E<raquo>> characters, for example, in a hash look-up: %hashB<I<E<laquo>>>keyB<I<E<raquo>>>

    Чтобы использовать именованные символы (E<>) внутри каждого C<...> достаточно поместить вначале документа следующую строку:

  • Код форматирования R<> используется для указания заменяемого элемента, маркера (placeholder) или метасинтаксической переменной. Данный текст обозначает элемент синтаксиса или спецификации, который в конечном итоге должен быть заменен на актуальное значение. Например:

    The basic ln command is: ln source_file target_file
    

    или:

    Then enter your details at the prompt:
    
            Name: your surname           ID: your employee number         Pass: your 36-letter password 

    Обычно заменяемые элементы отображаются наклонным шрифтом фиксированной ширины или обрамляются тэгами < <var>...</var> >. Гарнитура используемого шифта такая же как для кода C<>, за исключением случаев, когда код R<> находится внутри кодов K<> или T<> ( или их эквивалентов: блоков =input или =output ). Тогда используются шрифты соответствующих кодов.

All Articles