Augusto Campos

16/06/2013

O arquivo de configuração do Axe 〄

O arquivo axe/axe_config.txt não vem incluído na instalação do seu Axe, mas você pode (e deve) copiar o arquivo axe/axe_config_exemplo.txt para que ele se torne o axe/axe_config.txt que você irá editar para fazer o seu blog funcionar.

Se tudo correr bem, este é o único arquivo (além dos seus posts, claro) que você irá precisar editar para fazer o seu blog funcionar.

Trata-se de um arquivo em PHP, portanto cuidado para preservar a sua sintaxe.

Veremos a seguir cada uma das opções do arquivo, com comentários.

Título, descrição breve e a URL de uma imagem para servir de ícone do blog:

$blogparms["BLOGTITLE"] = 'Meu Blog';
$blogparms["BLOGMOTTO"] = "Testando o CMS AXE... e aprovando";
$blogparms["BLOGLOGO"] = "http://www.seu-site.com/img/bloglogo.png";

URL da raiz do blog, terminando com uma barra:
$blogparms["BLOGURL"] = 'http://seu-site.com/blog/';

Diretório em que está o executável axe.php:
$axedir='/users/fulano/www/blog/axe/';

Dentro do diretório acima precisam existir os diretórios a seguir:

• staging - é onde você grava os arquivos-texto de entrada contendo os seus posts, em txt puro ou com HTML.
• drafts - onde o Axe grava os posts pré-publicados, prontos para preview, postar ou atualizar.
• descriptors - onde o Axe grava os arquivos de dados correspondentes aos posts já publicados.

Twitter do blog, sem @
$blogparms["BLOGTWITTER"] = 'blogtwitter';

URL para acesso externo ao feed
$blogparms["FEEDURL"] = 'http://seu-site.com/blog/feed.xml';

Dados de identificação do autor do blog: nome, URL, twitter (sem @)
$blogparms["BLOGOWNER"] = 'Fulano de Tal';
$blogparms["BLOGOWNERURL"] = 'http://url-do-dono.com/';
$blogparms["BLOGOWNERTWITTER"] = 'donotwitter';

Quantidade de posts no feed, e de posts e de destaques na capa
$blogparms["NUMPOSTSFEED"] = '10';
$blogparms["NUMPOSTSCOVER"] = '10';
$blogparms["NUMFEATSCOVER"] = '2'; // numero de destaques na capa

(observação: nem todo tema diferencia destaques e posts)

Diretório dos temas no servidor
$blogparms["THEMESDIR"] = '/users/fulano/www/blog/axethemes/';

Caminho web dos temas (em relação à raiz do blog). Começa sem e termina com /
$blogparms["THEMESPATH"] = 'axethemes/';

Pasta do tema do blog (dentro do THEMESDIR/THEMESPATH)
$blogparms["THEME"] = 'panzer/';

Diretório-base dos plugins
$blogparms["PLUGINSDIR"] = $axedir.'plugins/';

Diretório-raiz do blog, onde constam os posts publicados em HTML, os indices, tags e feed, bem como os subdiretórios axe e axethemes:
$blogparms["POSTSDIR"] = '/users/fulano/www/blog/';

Caminho web da raiz até o diretório de posts. Começa sem "/" e termina com "/"
O caso normal é esta variável ficar vazia. //TO-DO: documentar o uso.
$blogparms["POSTSURLPREFIX"] = '';

Diretório onde serão gravados os previews (em HTML) de posts, gerados pelo axe.php -v
$blogparms["PREVIEWDIR"] = '/users/fulano/www/blog/axepreview/';

# A URL completa do diretório de previews. Termina com "/"
$blogparms["PREVIEWSBASEURL"] = 'http://seu-site.com/blog/axepreview/';

Idioma, verbosidade e localização. Na dúvida, não altere.
$blogparms["BLOGLOCALE"] = 'pt_BR';
error_reporting(E_ALL ^ E_NOTICE ^ E_USER_NOTICE);
date_default_timezone_set('America/Sao_Paulo');

Após editar, grave-o com o nome de axe/axe_config.php e você já poderá experimentar os comandos básicos do Axe.

Os arquivos que definem o tema

Se você for editar ou alterar um tema, segue a lista dos arquivos que a versão atual do Axe suporta. Eles residem imediatamente abaixo da pasta do tema – na configuração default, eles estão em axethemes/panzer/.

Cabeçalho e rodapé HTML, aplicáveis à capa, índices e posts individuais:

• header.php - se o seu tema tiver sidebar esquerda, insira-a aqui, juntamente com o cabeçalho.
• footer.php - se o seu tema tiver sidebar direita, insira-a aqui, juntamente com o rodapé.

Posts da capa e índices, incluindo o de tags:

• capa-post.php - post genérico
• capa-feat.php - post destaque da capa
• capa-news.php - post do tipo NEWS (veja detalhes em Como nasce um post no Axe: o arquivo de entrada)

Arquivo individual do post:

• single-body.php - o post em si
• single-body-preview.php - uma visualização adicional incluída abaixo do rodapé no momento do preview (opcional)

Feed RSS: cabeçalho, item e rodapé

• feed.header
• feed.item
• feed.footer

Comandos básicos do Axe

A comunicação entre o usuário e o Axe ocorre por meio de parâmetros do executável axe.php no seu Terminal, e é por isso que o Axe tem como requisito o acesso shell (ssh ou similar) ao servidor de hospedagem.

Para emitir os comandos, você pode chamar o axe.php pelo seu caminho completo, como no exemplo a seguir, que recriaria os índices do seu blog:

/users/fulano/www/blog/axe/axe.php -R

Outra alternativa é usar as expansões da shell, conforme a configuração da sua conta, como no exemplo:

~/www/blog/axe/axe.php -R

Ou ainda ir ao diretório do Axe e chamá-lo de lá:

cd ~/www/blog/axe
./axe.php -R

Usuários experientes certamente preferirão criar um alias ou mesmo incluir o Axe no path da sua shell.

Os parâmetros essenciais

Não esqueça de antes entender a estrutura de pastas do Axe e o ciclo de vida de um post do Axe.

Veja como comandar o Axe, com comandos curtos (exemplo: -d) e longos (exemplo: --draft):

• axe.php -d nome.txt
  --draft: pré-publica um post a partir de um arquivo de entrada gravado na pasta staging.

  axe.php -v nome.php

  --preview: cria, a partir de um draft gerado pelo axe.php -d, uma versão completa do post em HTML para conferência na pasta de previews, mas não a publica. A URL para que ela possa ser acessada pelo autor é exibida na tela.

  axe.php -P nome.php

  --post: publica um post em HTML puro a partir de um draft gerado pelo axe.php -d, e atualiza o index, as tags, o sitemap e o feed.

  axe.php -U nome.php

  --update: atualiza um post a partir de um draft gerado pelo axe.php -d, e atualiza o index, as tags, o sitemap e o feed. O arquivo de entrada que gera um draft de atualização tem requisitos especiais: incluir as variáveis @@POSTTIME e @@POSTNAME correspondentes à publicação inicial. Elas podem ser geradas automaticamente, veja na documentação sobre ciclo de vida de um post do Axe os detalhes sobre o acesso rápido ao fonte de um post para atualização.

  axe.php -X /AAAA/MM/nome.html

  --delete: apaga um post a partir da sua URL relativa (/ano/mes/nome.html), e atualiza o index, as tags e o feed.

  axe.php -e

  --feed: força atualizar o feed, mesmo sem ter publicado ou atualizado nada.

  axe.php -R

  --rebuild: força atualizar o index, as tags, o sitemap e o feed, mesmo sem ter publicado ou atualizado nada.

  axe.php -L

  --catalogs: para manutenção. Força a recriação, a partir dos posts arquivados, os catálogos internos de posts e de tags, usados para fazer os rebuilds.

  axe.php -m

  --map: Atualiza apenas o sitemap.

  axe.php -M

  --monthly: Atualiza apenas os índices mensais (archive*.html).

Os parâmetros modificadores

Alguns dos parâmetros essenciais do Axe, acima, aceitam modificadores, na forma de parâmetros adicionais. Por exemplo, se você quiser que o comando de rebuild atualize todos os índices e posts do blog, mesmo nos casos em que ele notar que já estão atualizados, pode trocar o parâmetro -R pelo parâmetro -Rf ou -R --force

Veja a lista de modificadores:

• -f
  --force: força o rebuild a atingir todos os arquivos, e não apenas os que precisam de atualização.

  -i

  --indexonly: Ao chamar 'axe.php -Ri', será feito um rebuild completo de todos os índices (index*.html, tag-*.html, archive*.html, sitemap-axe.xml e o feed rss), mas não dos arquivos de posts individuais (que também seriam reconstruídos no caso de um 'axe.php -Rf').

  -q

  --quiet: reduz as mensagens exibidas pelo Axe no Terminal.

  -t

  --talkative: aumenta a quantidade de mensagens exibidas pelo Axe no Terminal.

  -n

  norebuild: usado em conjunto com os comandos de post, update ou delete, impede que os índices, tags e feeds sejam atualizados automaticamente ao final da operação. Eles ficarão desatualizados, lembre-se de comandar um rebuild logo depois.

  -o

  --noold: usado em conjunto com o comando de draft, impede que o arquivo-texto de entrada seja movido automaticamente para a pasta old ao final da operação.

  -1

  --nofirstimage: não usa a primeira ilustração do post como um ícone para o mesmo (veja os detalhes no exemplo do arquivo de entrada).

  axe.php -r

  --strict: esta opção¹ desabilita qualquer significado especial para as 2 primeiras linhas do arquivo txt de entrada, que passam a ser meras linhas do corpo de texto. Ao usá-la, o título e as tags do post passam a ter de ser definidos com as linhas @@POSTTITLE: e @@POSTTAGS: ao final do arquivo txt de entrada.

  axe.php -h

  --hereconf: Permite executar um Axe instalado em outro diretório, e fazê-lo ler o axe_config.php do diretório corrente, e não do diretório em que o Axe reside. Casos de uso: múltiplas instalações do Axe no mesmo ambiente, ou Axe instalado fora da árvore de diretórios do servidor web.

Combinando parâmetros

Além de poder combinar parâmetros essenciais aos parâmetros modificadores, é possível combinar o parâmetro do comando draft (-d) aos dos comandos preview (-v), post (-P) e update (-U).

Exemplos:

• axe.php -dv nome.txt
  draft+preview: pré-publica um post a partir de um arquivo de entrada gravado na pasta staging, e cria uma versão completa do post em HTML para conferência na pasta de previews, sem publicá-la. A URL para que ela possa ser acessada pelo autor é exibida na tela.

  axe.php -dP nome.txt

  draft+post: pré-publica um post a partir de um arquivo de entrada gravado na pasta staging, gera o post correspondente em HTML e o publica, atualizando index, tags, sitemap e feed.

  axe.php -dPn nome.txt

  draft+post+norebuild: pré-publica um post a partir de um arquivo de entrada gravado na pasta staging, gera o post correspondente em HTML e o publica, mas sem atualizar index, tags, sitemap e feed.

Como nasce um post no Axe: o arquivo de entrada

Os atos de postar e editar conteúdo no Axe exigem um passo prévio: a pré-publicação (ou draft), que converte o arquivo TXT original (que você gerou com o seu texto) em uma forma pronta para ser publicada ou atualizada.

O ciclo de vida de um post é composto pela sequência básica a seguir, incluindo passos opcionais:

1. Um arquivo-texto de entrada é gravado pelo usuário no diretório axe/staging
2. Por meio do comando axe.php -d nome-arquivo.txt este arquivo-texto de entrada é pré-publicado (draft) e gravado no diretório axe/drafts
3. Opcionalmente, por meio do comando axe.php -v nome-arquivo.php, pode ser gerado um preview para verificação pelo autor, sem publicação. Caso haja correções ou alterações, basta editar o arquivo-texto de entrada original e gravá-lo novamente, voltando ao passo 1.
4. Ao decidir publicar, o usuário emite o comando axe.php -P nome-arquivo.php e o arquivo é publicado em HTML, acompanhado de atualização do index, das tags, do sitemap e do feed.
5. Caso um dia seja necessário atualizar um arquivo já publicado, o Axe pode gerar uma versão atualizada do arquivo-texto de entrada, que você pode copiar para o seu editor de textos favoritos e repetir os passos 1 a 3 (mas não o passo 4), e posteriormente comandar a atualização pelo comando axe.php -U nome-arquivo.php

Estrutura do arquivo-texto de entrada do Axe

O arquivo-texto de entrada do Axe pode ser criado no seu editor de textos favorito (vale até o Bloco de Notas), desde que ele grave em um formato de texto simples (.TXT). O Axe espera receber arquivos txt com acentuação padrão Unicode, que é a default na maioria dos aplicativos modernos. Verifique a documentação do seu editor, se necessário.

Cada arquivo pode ter o nome que você preferir, mas sem espaços nem caracteres especiais no nome (hífen e sublinhado pode).

O arquivo precisa ter, no mínimo, os seguintes elementos:

Este é o título do meu post
tags: exemplo,axe,manual,arquivo,texto

Aqui é o primeiro parágrafo do meu post. 

Aqui é o segundo parágrafo do meu post, mas ele 
poderia nem existir. 

Vamos descrevê-los:

1. O título, sem necessidade de qualquer formatação especial, desde que você não insira qualquer quebra de linha nele.
2. A linha de tags (separadas por vírgulas) é recomendável, mas opcional.
3. A partir daqui é uma sequência de parágrafos de texto (com uso opcional de HTML), separados por linhas em branco.

Sim, você pode incrementar a estrutura e formatação do seu post com uso de HTML:

Este é o título do meu post
tags: exemplo,axe,manual,arquivo,texto

Aqui é o primeiro parágrafo do meu post. 

Note que até aqui não tem nada de HTML.

Mas <strong>se você quiser</strong>, pode 
inseri-las diretamente no texto. 

O mesmo vale para listas, imagens, 
tabelas, citações, etc.

Este é o quarto parágrafo do texto.

Não há suporte a outras linguagens populares de marcação, como textile, txt2tags ou Markdown, porque eu não as uso. Mas é fácil ativar esse suporte por meio de um plugin para o Axe, e não duvido que algum usuário empreendedor disponibilize logo esse recurso ツ

Mas há um recurso especial, que o HTML em si não suporta diretamente¹ mas o Axe incluiu "por fora", com uma sintaxe própria: as notas de rodapé². As notas de rodapé devem ser inseridas no local em que serão referenciadas, colocadas entre colchetes e precedidas de "@@rod:", conforme o exemplo a seguir:

Este é o título do meu post
tags: exemplo,axe,manual,arquivo,texto

Aqui é o primeiro parágrafo do meu post. 

Aqui é o segundo parágrafo do meu post, mas ele 
poderia[@@rod:E aqui vem o texto da nota de rodapé] nem existir. 

As notas são numeradas sequencialmente, aparecem automaticamente ao final do post (ou seja, no rodapé) e também como um hover no seu número, inline. Junto a cada nota, no rodapé, há um link para retornar ao seu contexto original.

Definindo variáveis do Axe no arquivo do post

É possível definir variáveis do Axe referentes ao seu post (como um ícone para o post, ou o horário em que o post deve ser publicado) no mesmo arquivo TXT em que o texto do post está definido.

As variáveis devem vir, uma por linha, no final do arquivo TXT, ou seja, abaixo do texto em si. Segue um exemplo simples que define um ícone para o post (para ser usado quando ele for mencionado no Facebook, por exemplo, ou da forma como o seu tema definir):

Este é o título do meu post
tags: exemplo,axe,manual,arquivo,texto

Aqui é o primeiro parágrafo do meu post. 

Aqui é o segundo parágrafo do meu post, mas ele 
poderia nem existir. 

@@POSTICON:http://foo.com/icone.jpg

Um detalhe importante: se o seu post for ilustrado por imagens em HTML (tag <img>), o Axe sempre definirá automaticamente como ícone para o post a primeira das imagens. Se você inseriu imagens no post mas desejar definir explicitamente por meio da variável @@POSTICON, como exemplificado acima, deverá usar o parâmetro --nofirstimage

Como ter acesso ao fonte original para atualizar um post

Quando você quiser atualizar um post, a forma mais conveniente de obter o seu texto original para copiar e colar no seu editor de textos preferido é usar o próprio Axe para isso.

Todo post publicado conta com o acesso rápido ao seu próprio texto original, por meio de uma URL terminando com .src.html?txt

Por exemplo, se o seu post estiver publicado como http://www.seusite.com/blog/2013/06/teste-do-axe.html o texto correspondente estará em http://www.seusite.com/blog/2013/06/teste-do-axe.src.html?txt - se desejar, experimente com a URL do post que você está lendo ツ

Esse acesso rápido ao texto original tem um detalhe providencial: já inclui ao seu final as variáveis @@POSTTIME e @@POSTNAME, ambas necessárias para que o post possa ser atualizado – portanto não as remova.

Um detalhe importante: embora ele esteja inserido em um campo editável do arquivo .src.html, você não pode editar o texto no próprio navegador para depois salvá-lo – é necessário copiar e colar para o seu editor de textos preferido, e realizar a edição nele, e depois repetir o seu procedimento normal de transferir o arquivo para o diretório axe/staging do seu servidor de hospedagem.

Como vimos no início deste texto, o parâmetro ('-U') para atualizar um post a partir de um TXT gravado no axe/staging é diferente do usado para publicar sua versão original.