perlpod - Online na nuvem

PROGRAMA:

NOME

perlpod - o formato de documentação simples e antigo

DESCRIÇÃO

Pod é uma linguagem de marcação simples de usar, usada para escrever documentação para Perl, Perl
programas e módulos Perl.

Os tradutores estão disponíveis para converter o Pod em vários formatos, como texto simples, HTML, man
páginas e muito mais.

A marcação de pod consiste em três tipos básicos de parágrafos: comum, literal e de comando.

Ordinário parágrafo
A maioria dos parágrafos em sua documentação serão blocos de texto comuns, como este. Você
pode simplesmente digitar seu texto sem qualquer marcação e com apenas uma linha em branco
antes e depois. Quando for formatado, passará por uma formatação mínima, como se fosse
embrulhado, provavelmente colocado em uma fonte com espaçamento proporcional e talvez até justificado.

Você pode usar códigos de formatação em parágrafos comuns, para pino, itálico, "estilo de código",
hiperlinks e muito mais. Esses códigos são explicados na seção "Códigos de formatação" abaixo.

Textualmente parágrafo
Parágrafos literais são geralmente usados ​​para apresentar um bloco de código ou outro texto que
não requerem nenhuma análise ou formatação especial e não devem ser quebradas.

Um parágrafo literal se distingue por ter seu primeiro caractere um espaço ou uma tabulação.
(E normalmente, todas as suas linhas começam com espaços e / ou tabulações.) Deve ser reproduzido
exatamente, com as guias presumidas em limites de 8 colunas. Não há formatação especial
códigos, então você não pode colocar em itálico ou algo assim. A \ significa \ e nada mais.

Command parágrafo
Um parágrafo de comando é usado para tratamento especial de pedaços inteiros de texto, geralmente como
títulos ou partes de listas.

Todos os parágrafos de comando (que normalmente têm apenas uma linha) começam com "=", seguido
por um identificador, seguido por um texto arbitrário que o comando pode usar como quiser.
Os comandos atualmente reconhecidos são

= pod
= head1 Texto do Título
= head2 Texto do Título
= head3 Texto do Título
= head4 Texto do Título
= over indentlevel
= item coisas
= voltar
= formato inicial
= formato final
= para formato de texto ...
= tipo de codificação
= corte

Para explicar cada um deles em detalhes:

"= head1 Título Texto"
"= head2 Título Texto"
"= head3 Título Texto"
"= head4 Título Texto"
Head1 a head4 produzem cabeçalhos, head1 sendo o nível mais alto. O texto no
o resto deste parágrafo é o conteúdo do título. Por exemplo:

= head2 Atributos do objeto

O texto "Atributos do objeto" compreende o título ali. O texto neste título
os comandos podem usar códigos de formatação, como visto aqui:

= head2 Valores Possíveis para C <$ />

Esses comandos são explicados na seção "Códigos de formatação" abaixo.

"= acabado indentlevel "
"= item coisa..."
"= voltar"
Item, over e back requerem um pouco mais de explicação: "= over" inicia uma região
especificamente para a geração de uma lista usando comandos "= item", ou para recuo
(grupos de) parágrafos normais. No final da sua lista, use "= back" para encerrá-la. O
nível interno opção para "= over" indica a distância até o recuo, geralmente em ems
(onde um em é a largura de um "M" na fonte base do documento) ou aproximadamente
unidades comparáveis; se não há nível interno opção, o padrão é quatro. (E alguns
os formatadores podem simplesmente ignorar o que quer que seja nível interno você fornece.) No coisas em "= item
coisa...", você pode usar códigos de formatação, como visto aqui:

= item Usando C <$ |> para controlar o buffer

Esses comandos são explicados na seção "Códigos de formatação" abaixo.

Observe também que existem algumas regras básicas para usar regiões "= over" ... "= back":

· Não use "= item" s fora de uma região "= over" ... "= back".

· A primeira coisa após o comando "= over" deve ser um "= item", a menos que haja
não haverá nenhum item nesta região "= over" ... "= back".

· Não coloque "= cabeçan"comandos dentro de uma região" = over "..." = back ".

· E talvez o mais importante, mantenha os itens consistentes: use "= item *" para
todos eles, para produzir balas; ou use "= item 1.", "= item 2.", etc., para produzir
listas numeradas; ou use "= item foo", "= item bar", etc .-- ou seja, coisas que parecem
nada como marcadores ou números.

Se você começar com marcadores ou números, continue com eles, pois os formatadores usam o primeiro
tipo "= item" para decidir como formatar a lista.

"= cortar"
Para encerrar um bloco de pod, use uma linha em branco, depois uma linha começando com "= cut" e um espaço em branco
linha depois disso. Isso permite que o Perl (e o formatador do Pod) saiba que é aqui que o Perl
o código está sendo retomado. (A linha em branco antes de "= cortar" não é tecnicamente necessária, mas
muitos processadores de pod mais antigos exigem isso.)

"= pod"
O comando "= pod" por si só não faz muita coisa, mas sinaliza para Perl (e
Formatadores de pod) que um bloco de pod começa aqui. Um bloco de pod começa com qualquer comando
parágrafo, portanto, um comando "= pod" geralmente é usado apenas quando você deseja iniciar um bloco de pod
com um parágrafo comum ou um parágrafo literal. Por exemplo:

= item stuff ()

Esta função faz coisas.

= corte

subcoisas {
...
}

= pod

Lembre-se de verificar seu valor de retorno, como em:

coisas () || morrer "Não foi possível fazer coisas!";

= corte

"= começar formatname "
"= fim formatname "
"= para nome do formato texto..."
For, begin e end permitem que você tenha regiões de texto / código / dados que geralmente não são
interpretados como texto de pod normal, mas são passados ​​diretamente para formatadores específicos, ou
são especiais. Um formatador que pode usar esse formato usará a região,
caso contrário, será completamente ignorado.

Um comando "= começar nome do formato", alguns parágrafos e um comando" = fim nome do formato", significar
que o texto / dados intermediários se destinam a formatadores que entendem o
formato chamado nome do formato. Por exemplo, a

= begin html


Este é um parágrafo HTML bruto

= end html

O comando "= para nome do formato texto..."especifica que o restante apenas deste
parágrafo (começando logo após nome do formato) está nesse formato especial.

= para html
Este é um parágrafo HTML bruto

Isso significa a mesma coisa que a região "= begin html" ... "= end html" acima.

Ou seja, com "= para", você pode ter apenas um parágrafo de texto (ou seja, o texto
em "= foo targetname text ..."), mas com "= begin targetname" ... "= end targetname", você
pode ter qualquer quantidade de material entre eles. (Observe que ainda deve haver uma linha em branco
após o comando "= begin" e uma linha em branco antes do comando "= end".)

Aqui estão alguns exemplos de como usá-los:

= begin html

Figura 1.

= end html

= começar o texto

---------------
| foo |
| barra |
---------------

^^^^ Figura 1. ^^^^

= texto final

Alguns nomes de formato que os formatadores aceitam atualmente incluem "roff", "man",
"latex", "tex", "text" e "html". (Alguns formatadores tratarão alguns deles como
sinônimos.)

Um nome de formato de "comentário" é comum apenas para fazer anotações (provavelmente para você mesmo)
que não aparecerá em nenhuma versão formatada do documento Pod:

= para comentário
Certifique-se de que todas as opções disponíveis estão documentadas!

Alguns nomes de formato exigirá dois pontos iniciais (como em "= for: formatname", ou "= começar
: formatname "..." = end: formatname "), para sinalizar que o texto não é um dado bruto, mas
em vez disso is Texto do pod (ou seja, possivelmente contendo códigos de formatação) que não é apenas para
formatação normal (por exemplo, pode não ser um parágrafo de uso normal, mas pode ser para
formatação como uma nota de rodapé).

"= codificação encodingname "
Este comando é usado para declarar a codificação de um documento. A maioria dos usuários não precisa
isto; mas se sua codificação não for US-ASCII, coloque uma codificação "= encodingname " comando
bem no início do documento, para que os formatadores de pod saibam como decodificar o
documento. Por nome de codificação, use um nome reconhecido pelo módulo Encode :: Supported.
Alguns formatadores de pod podem tentar adivinhar entre um Latin-1 ou CP-1252 e UTF-8
codificação, mas eles podem adivinhar errado. É melhor ser explícito se você usar algo
além de ASCII estrito. Exemplos:

= codificação latin1

= codificação utf8

= codificação koi8-r

= codificação ShiftJIS

= codificação big5

"= codificação" afeta todo o documento e deve ocorrer apenas uma vez.

E não se esqueça, todos os comandos, exceto "= encoding" duram até o final de seu parágrafo, não
sua linha. Nos exemplos abaixo, você pode ver que todo comando precisa da linha em branco
depois, para encerrar seu parágrafo. (E alguns tradutores de Pod mais antigos podem exigir o
linha "= codificação" para ter uma linha em branco a seguir, embora deva ser legal para
omitir.)

Alguns exemplos de listas incluem:

= acabado

= item *

Primeiro item

= item *

Segundo item

= voltar

= acabado

= item Foo ()

Descrição da função Foo

= item Bar ()

Descrição da função Bar

= voltar

formatação códigos
Em parágrafos comuns e em alguns parágrafos de comando, vários códigos de formatação (também conhecidos como
"sequências interiores") podem ser usadas:

"EU "- texto em itálico
Usado para ênfase ("" seja eu "") e parâmetros ("" refazer I "")

"B " -- texto em negrito
Usado para interruptores ("" switch B <-n> do perl ""), programas ("" alguns sistemas fornecem um
B para aquele ""), ênfase ("" seja B "") e assim por diante ("" e esse recurso é
conhecido como B "").

"C " -- code text
Renderiza o código em uma fonte de máquina de escrever ou dá alguma outra indicação de que isso representa
texto do programa ("" C "") ou alguma outra forma de computador
("" C "").

"EU "- um hiperlink
Existem várias sintaxes, listadas abaixo. Nas sintaxes fornecidas, "texto", "nome" e
"seção" não pode conter os caracteres '/' e '|'; e qualquer '<' ou '>' deve ser
coincide.

· "EU "

Link para uma página de manual Perl (por exemplo, "L "). Observe que" nome "não deve
conter espaços. Esta sintaxe também é ocasionalmente usada para referências ao Unix man
páginas, como em "Lcrontab(5)> ".

· "EU "ou" L "

Link para uma seção em outra página do manual. Por exemplo, "L "

· "EU "ou" L "

Link para uma seção nesta página de manual. Por exemplo, "L "

Uma seção é iniciada pelo título ou item nomeado. Por exemplo, "L " ou
"EU "ambos ligam para a seção iniciada por" "= item $." "em perlvar. E
"EU "ou" L "ambos ligam para a seção iniciada por
"" = head2 For Loops "" em perlsyn.

Para controlar qual texto é usado para exibição, você usa "" L "", como em:

· "EU "

Vincule este texto a essa página do manual. Por exemplo, "L "

· "EU "ou" L "

Vincule este texto a essa seção na página do manual. Por exemplo, "L
"if" | perlsyn / "Modificadores de instrução"> "

· "EU "ou" L "ou" L "

Vincule este texto a essa seção nesta página do manual. Por exemplo, "L
atributos | / "Dados do membro"> "

Ou você pode criar um link para uma página da web:

· "EU "

"EU "

Links para um URL absoluto. Por exemplo, "Lhttp://www.perl.org/> "ou" L
Página inicial |http://www.perl.org/> ".

"E "- um escape de personagem
Muito semelhante a HTML / XML "&foo; " "referências de entidade":

· "E "- um literal <(menor que)

· "E "- um literal> (maior que)

· "E "- um literal | (vertico Barra)

· "E "- um literal / (solid)

Os quatro acima são opcionais, exceto em outros códigos de formatação, notavelmente "L <...>",
e quando precedido de letra maiúscula.

· "E "

Algum nome de entidade HTML não numérico, como "E ", significando a mesma coisa que
"é" em HTML - ou seja, um e minúsculo com um acento agudo (em forma de /).

· "E "

O caractere ASCII / Latin-1 / Unicode com esse número. Um "0x" inicial significa que
número é hexadecimal, como em "E <0x201E>". Um "0" inicial significa que número é octal, como em
"E <075>". De outra forma número é interpretado como sendo decimal, como em "E <181>".

Observe que os formatadores de Pod mais antigos podem não reconhecer escapes numéricos octais ou hexadecimais,
e que muitos formatadores não podem renderizar de forma confiável caracteres acima de 255. (Alguns
os formatadores podem até ter que usar renderizações comprometidas de Latin-1 / CP-1252
caracteres, como renderização "E "como apenas um" e "simples.)

"F "- usado para nomes de arquivos
Normalmente exibido em itálico. Exemplo: "" F <.cshrc> ""

"S "- o texto contém espaços não separáveis
Isso significa que as palavras em texto não deve ser interrompido em linhas. Exemplo:
"S <$ x? $ Y: $ z>".

"X "- uma entrada de índice
Isso é ignorado pela maioria dos formatadores, mas alguns podem usá-lo para construir índices. Isto
sempre renderiza como string vazia. Exemplo: "X "

"Z <>" - um código de formatação nulo (efeito zero)
Isso raramente é usado. É uma maneira de contornar o uso de um código E <...> às vezes. Por
exemplo, em vez de "" NE 3 "" (para "N <3") você pode escrever "" NZ <> <3 "" (o "Z <>"
divide o "N" e o "<" para que não possam ser considerados parte de um (fictício)
Código "N <...>").

Na maioria das vezes, você precisará apenas de um único conjunto de colchetes angulares para delimitar o
início e fim dos códigos de formatação. No entanto, às vezes você vai querer colocar um verdadeiro
colchete angular direito (um sinal de maior que, '>') dentro de um código de formatação. Isto é
particularmente comum ao usar um código de formatação para fornecer um tipo de fonte diferente para um
trecho de código. Como com todas as coisas em Perl, há mais de uma maneira de fazer isso. Um
maneira é simplesmente escapar do colchete de fechamento usando um código "E":

C <$ a E = E $ b>

Isso produzirá: "" $ a <=> $ b ""

Uma forma mais legível e talvez mais "simples" é usar um conjunto alternativo de delimitadores
isso não requer que um único ">" seja escapado. Colchetes angulares duplos ("<<" e ">>")
pode ser usado if e só if lá is espaço em branco certo depois de da abertura delimitador e
espaço em branco certo antes da encerramento delimitador! Por exemplo, o seguinte fará o
truque:

C << $ a <=> $ b >>

Na verdade, você pode usar quantos colchetes angulares repetidos quiser, desde que tenha o
mesmo número deles nos delimitadores de abertura e fechamento, e certifique-se de que os espaços em branco
segue imediatamente o último '<' do delimitador de abertura e precede imediatamente o
primeiro '>' do delimitador de fechamento. (O espaço em branco é ignorado.) Portanto, o seguinte
também funcionam:

C <<< $ a <=> $ b >>>
C <<<< $ a <=> $ b >>>>

E todos eles significam exatamente o mesmo:

C <$ a E = E $ b>

A forma de colchetes não afeta a interpretação do conteúdo do
formatando o código, apenas como ele deve terminar. Isso significa que os exemplos acima também são
exatamente o mesmo que este:

C << $ a E = E $ b >>

Como outro exemplo, isso significa que se você quiser colocar esses pedaços de código em "C"
estilo (código):

abrir (X, ">> thing.dat") || morra $!
$ foo-> bar ();

você poderia fazer assim:

C <<< open (X, ">> thing.dat") || morra $! >>>
C << $ foo-> bar (); >>

que é presumivelmente mais fácil de ler do que a maneira antiga:

C E thing.dat ") || die $!>
C <$ foo-E bar ();>

Isso é atualmente compatível com pod2text (Pod :: Text), pod2man (Pod :: Man) e qualquer outro
tradutores pod2xxx ou Pod :: Xxxx que usam Pod :: Parser 1.093 ou posterior, ou Pod :: Tree 1.02 ou
mais tarde.

O Intenção
A intenção é a simplicidade de uso, não o poder de expressão. Parágrafos parecem parágrafos
(formato de bloco), para que se destaquem visualmente e para que eu possa percorrê-los
"fmt" facilmente para reformatá-los (isso é F7 na minha versão do viou Esc Q na minha versão de
emacs) Eu queria que o tradutor sempre deixasse as citações "'" e "` "e" "" sozinhas, em
modo literal, para que eu pudesse engolir um programa de trabalho, deslocá-lo em quatro espaços e ter
imprimir, er, literalmente. E provavelmente em uma fonte monoespaçada.

O formato do pod não é necessariamente suficiente para escrever um livro. Pod é apenas para ser
uma fonte comum à prova de idiotas para nroff, HTML, TeX e outras linguagens de marcação, conforme usado para
documentação online. Existem tradutores para pod2text, pod2html, pod2man (isso é para
nroff(1) e troff(1)), pod2latex e pod2fm. Vários outros estão disponíveis no CPAN.

Incorporação vagens in Perl Módulos
Você pode incorporar a documentação do Pod em seus módulos e scripts Perl. Comece o seu
documentação com uma linha em branco, um comando "= head1" no início e finalize com um
comando "= cut" e uma linha vazia. O perl executável irá ignorar o texto do pod. Você pode
coloque uma declaração de pod onde perl espera o início de uma nova declaração, mas não dentro
uma declaração, pois isso resultaria em um erro. Veja qualquer um dos módulos de biblioteca fornecidos
por exemplo.

Se você for colocar seu pod no final do arquivo e estiver usando um "__END__" ou
"__DATA__" marca de corte, certifique-se de colocar uma linha vazia antes do primeiro comando do pod.

__FIM__

= head1 NAME

Hora :: Local - calcule a hora de forma eficiente a partir da hora local e GMT

Sem essa linha vazia antes de "= head1", muitos tradutores não teriam reconhecido o
"= head1" como iniciando um bloco de pod.

Dicas for Escrevendo Vagem
·

O verificador de pod O comando é fornecido para verificar a sintaxe do Pod em busca de erros e avisos.
Por exemplo, ele verifica se há linhas completamente em branco em blocos de pods e desconhecidos
comandos e códigos de formatação. Você ainda deve passar seu documento por um
ou mais tradutores e revisar o resultado, ou imprimir o resultado e revisar
naquela. Alguns dos problemas encontrados podem ser bugs nos tradutores, que você pode ou pode
não deseja contornar.

· Se você está mais familiarizado com a escrita em HTML do que com a escrita em Pod, pode tentar
sua mão escrevendo documentação em HTML simples e convertendo-a em Pod com o
Módulo Pod :: HTML2Pod experimental, (disponível no CPAN), e olhando para o resultado
código. O módulo experimental Pod :: PXML no CPAN também pode ser útil.

· Muitos tradutores de Pod mais antigos exigem as linhas antes de cada comando de Pod e após cada
O comando do pod (incluindo "= cut"!) Deve ser uma linha em branco. Ter algo assim:

# - - - - - - - - - - - - -
= item $ firecracker-> boom ()

Isso detona ruidosamente o objeto foguete.
= corte
sub-explosão {
...

... fará com que esses tradutores de Pod não consigam ver o bloco de Pod.

Em vez disso, faça assim:

# - - - - - - - - - - - - -

= item $ firecracker-> boom ()

Isso detona ruidosamente o objeto foguete.

= corte

sub-explosão {
...

· Alguns tradutores de Pod mais antigos exigem parágrafos (incluindo parágrafos de comando como
"= funções head2") a serem separadas por completamente linhas vazias. Se você tem um
linha aparentemente vazia com alguns espaços, isso pode não contar como um separador para
esses tradutores e isso pode causar uma formatação estranha.

· Tradutores mais antigos podem adicionar texto ao redor de um link L <>, de modo que "L " poderia
torne-se "a página de manual Foo :: Bar", por exemplo. Portanto, você não deve escrever coisas como "o
eu documentação ", se você quiser que o documento traduzido seja lido de maneira sensata. Em vez disso,
escreva "o L documentação "ou" L
documentação | Foo :: Bar> ", para controlar como o link sai.

· Ir além da 70ª coluna em um bloco literal pode ser embrulhado de maneira deselegante por alguns
formatadores.

Use perlpod online usando serviços onworks.net