4.1 Sintaxe
Caracteres (Character Set)
A linguagem DMHelp é utilizada em arquivos texto onde são aceitos os seguintes caracteres (Character Set):
|
Legenda:
|
Formato
Os textos podem ser digitados em formato livre considerando-se:
Cada conjunto de caracteres "em branco" (espaços e tabs) será substituído por um espaço (a não ser que sejam os primeiros ou últimos espaços de um parágrafo, quando são desprezados).
Cada conjunto de linhas em branco será "substituído" por uma mudança de parágrafo.
Uma única mudança de linha não é considerada mudança de parágrafo.
|
Este parágrafo contém Tabs e espaços entre as palavras,
tendo, inclusive, mudança de uma única linha
aqui o que não casusa mudança de parágrafo.
Com uma ou mais linhas em branco, aí sim, teremos uma única mudança
de parágrafo.
|
|
Este parágrafo contém Tabs e espaços entre as palavras, tendo, inclusive, mudança de uma única linha aqui o que não casusa mudança de parágrafo.
Com uma ou mais linhas em branco, aí sim, teremos uma única mudança de parágrafo.
|
Chaves ({ e })
As regras do Formato (explicadas acima) só valem se não forem envolvidas entre chaves ({ e }), ou seja, tudo que vier entre chaves será considerado como se fosse uma única "palavra" e será transferido para os arquivos de saída.
As chaves são "encadeáveis" ou seja se você "abrir" uma chave ({) digitar algo, e "abrir" outra, esta última será considerada como "parte" da mesma "palavra" que só terminará quando você "fechar" duas chaves (}).
Assim sendo, se você "abrir" 3 chaves, a "palavra" termina quando você "fechar" a 3a. chave, o mesmo valendo para 4, 5, etc. chaves.
|
{Este parágrafo é considerado como se fosse
uma única palavra e tudo o que for digitado
como, por exemplo (<, >, {, }) é considerado
parte da mesma.}
|
|
Este parágrafo é considerado como se fosse
uma única palavra e tudo o que for digitado
como, por exemplo (<, >, {, }) é considerado
parte da mesma.
|
A formatação fica "distorcida" pois tudo o que foi digitado entre as chaves foi aplicado "literalmente" nos arquivos de saídas (inclusive espaços, tabs, e mudanças de linha).
Não é comum a utilização de chaves com várias linhas entre elas.
As chaves foram escolhidas como delimitadoras de literais ao invés da tradicional aspas ( " ) ou single-quote ( ' ) utilizadas em várias linguagens. Isto porque, em um manual é muito comum a utilização das aspas como "agora" (por exemplo).
Comentários (// e /* ... */)
Da mesma forma que na linguagem C a linguagem DMHelp aceita comentários de linha e de bloco.
Comentários de linha são definidos pela sequência // o que indica que tudo o que "vier" após isso, e até o final da linha não será adicionado nos arquivos de saída.
Comentários de bloco começam com /* e terminam com */ e indicam que tudo o que "vier" entre eles não será adicionado nos arquivos de saída.
|
Este parágrafo // Note aqui um comentário de linha
possue comentários /*
Este trecho também não aparece
pois temos aqui um comentário de bloco
*/
"embebidos".
|
|
Este parágrafo possue comentários "embebidos".
|
Comentários permitem uma melhor documentação e observações internas ao seu documento.
Se você "abrir" um comentário de bloco mas não fechá-lo, não será gerada mensagem de erro, porém, tudo desse ponto até o fim do arquivo será desprezado.
Se isso ocorrer dentro de um arquivo incluído (pelo comando IN (<IN [atributos]>) descrito mais adiante), somente os dados do arquivo incluído serão desprezados, prosseguindo normalmente a conversão após o comando que incluiu esse arquivo.
Comandos (< ... >)
Tudo o que estiver entre os sinais < e > são considerados comandos da linguagem DMHelp.
Esses caracteres foram escolhidos para manter uma aparência semelhante com os tradicionais arquivos na linguagem HTML.
A sintaxe de um comando é:
<(Nome do comando) [Atributo = Valor] ... [Atributo = Valor]>
O nome do comando do comando é obrigatório, porém os atributos poderão, ou não, existir.
O sinal igual ( = )
Conforme observado o sinal igual é considerado um caractere normal (como aqui "=", por exemplo) a não ser quando estiver dentro de um comando, onde será indicador de divisão entre o nome de um Atributo e seu Valor.
Escape character ( \ )
Quando você desejar incluir os caracteres especiais (descritos acima) nos seus documentos, deve precedê-los pelo escape character ( \ ), ou seja, o escape character ( \ ) faz com que o caractere seguinte (qualquer que seja ele) seja aplicado literalmente no seu documento.
Preceder um caractere com o escape character ( \ ) é exatamente o mesmo que envolvê-lo entre chaves ({ e }).
|
Aplicação dos caracteres especiais:
\{ e \} (chaves),
\/\/ (comentários de linha),
\/* e *\/ (comentários de bloco),
\< e \> (delimitadores de comandos),
\\ (o próprio caractere de escape), e, finalmente,
\a, \ , \ , \etc. (quaisquer caracteres, incluindo
spaces, tabs, letras, números, etc.)
|
|
Aplicação dos caracteres especiais: { e } (chaves), // (comentários de linha), /* e */ (comentários de bloco), < e > (delimitadores de comandos), \ (o próprio caractere de escape), e, finalmente, a, , , etc. (quaisquer caracteres, incluindo spaces, tabs, letras, números, etc.)
|
Note que o caractere igual (=) não precisa (embora possa) ser precedido pelo escape character ( \ ) pois somente é aplicado dentro dos comandos (entre < e >).
NÃO é case sensitive
A linguagem DMHelp não é case-sensitive, ou seja, todos os comandos e nomes de atributos podem ser digitados em letras maiúsculas, minúsculas, ou mistura delas.
O mesmo não vale para os valores dos atributos que serão, nesse caso, aplicados do mesmo modo como forem digitados.