Axe 0.98a.2 - Download e instruções de uso

A versão atual do gerenciador de conteúdo estático Axe é a 0.98a.2, o segundo alfa público do gerenciador de conteúdo Axe, criado para uso no BR-Linux.org, BR-Mac.org e Efetividade.net (e disponível a outros interessados aventureiros). Saiba mais: o que é o Axe.

Atenção: trata-se de versão Alfa, e seu público-alvo são os desenvolvedores interessados em testá-lo. Após um novo período de testes alfa, previsto para durar 3 semanas, o Axe deve entrar em versão beta, já voltada a testes por usuários, e aí incluindo o script de importação de blogs baseados no WordPress, que talvez precise passar também por um período de testes antes de ser considerado estável (mas já foi usado para importar meus 3 blogs).

Atualmente a instalação exige algum conhecimento de administração de servidores, e intimidade com o terminal e a shell. Não há previsão de que isso mude no futuro.

Instruções básicas

Lendo os artigos "Estrutura de diretórios e arquivos do Axe" e "O arquivo de configuração do Axe" você deverá estar apto a instalar e configurar. Todas as instruções pressupõem que você sabe operar o seu servidor web e mantê-lo seguro.

O artigo "Comandos básicos do Axe" explica como operá-lo, o "Como nasce um post no Axe: o arquivo de entrada" explica como é criado (e atualizado) um post, e em "As variáveis de exibição para usar no seu tema" você descobre como personalizar o visual do seu blog, modificando seu tema ou criando outro.

Usuários avançados e desenvolvedores terão interesse também nos artigos sobre agendamento de posts e sobre criação de plugins para o Axe.

Atenção: o Axe vem com 2 arquivos .htaccess que, em servidores web com configurações comuns e suporte ao mod_rewrite, impedirão que sites de busca indexem os arquivos de dados do Axe, sem impedir que eles indexem normalmente o conteúdo que você publicar. Se o seu servidor tiver necessidades especiais, configure-os de acordo.

Recomendação expressa e clara: instale esta versão do Axe em um diretório à parte no seu sistema, e não dependa dela para nada antes de testar se ela faz o que você deseja. O Axe foi criado para meu uso pessoal e será um prazer se você também tiver interesse em usá-lo e conseguir fazê-lo, mas não ofereço nenhum suporte ou garantia.

Dica extra: a primeira linha do arquivo axe/axe.php é #!/usr/bin/php e aponta para a localização do interpretador do PHP nos servidores mais comuns. Se necessário (por exemplo, se você receber o erro "Bad interpreter"), edite-a para apontar para a localização correta do PHP 5.3 ou superior no seu sistema, que o provedor de hospedagem poderá lhe informar. No caso do Dreamhost, por exemplo, ela deve ficar assim: #!/usr/local/bin/php-5.3

O Axe é software livre e open source, sob a licença Apache 2.0.

Download desta versão alfa do Axe: Axe 0.98a.2.

Se você estiver fazendo upgrade, simplesmente faça um backup e depois sobreponha a versão anterior. Note que o seu arquivo axe_config.php não será sobreposto, pois ele não é incluído no pacote. O seu tema também não será sobreposto, pois a nova versão vem com um tema chamado panzer3, ligeiramente modificado e atualizado (para suporte a itens como as notas de rodapé). Recomendo que altere sua configuração para passar usá-lo e faça um rebuild completo (axe.php -Rf).

Não há suporte, nem serviços, e especialmente não há nenhuma garantia. Para relatar problemas, enviar a solução deles ou buscar recorrer à ajuda dos demais usuários, inscreva-se na lista axe-users (baixo tráfego, usualmente).

Mudanças da versão 0.98a.2

  1. A definição do arquivo-texto de entrada mudou: agora só as 2 primeiras linhas têm significado especial nato. A primeira sempre é o título do post, e a segunda (opcionalmente, apenas quando iniciar com "tags:") é a lista de tags. Na versão anterior, a segunda linha indicava um ícone para o post, para ser usado (por exemplo) por temas e por redes sociais, na forma da variável %%POSTICON%%.
  2. O ícone de cada post (%%POSTICON%% ou @@POSTICON) passou a ser definido automaticamente como a URL da primeira imagem referenciada no post. Se você desejar definir manualmente qual a imagem que servirá de ícone para o post, inclua a URL dela na definição @@POSTICON (uma linha como esta ao final do post: @@POSTICON:http://foo.net/icone.jpg) e chame o axe.php com a opção '--nofirstimage' (ou '-1' – é um número um, e não um L minúsculo).
  3. O Axe agora tem suporte a notas de rodapé, que devem ser definidas entre colchetes e precedidas de "@@rod:", conforme o exemplo a seguir: "Este é um texto comum[@@rod:E aqui vem o texto da nota de rodapé dele] para exemplo.". As notas são numeradas sequencialmente, aparecem 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.
  4. O Axe agora tem suporte a cron e permite agendar posts para entrar em determinado dia e hora (como faço no BR-Mac, onde os posts entram no ar às 7h30, enquanto durmo). O recurso funciona por polling, com a crontab chamando o Axe (com o parâmetro -c) periodicamente, e o Axe se encarregando de verificar se tem algo a publicar naquele momento.
  5. Por sugestão do Aurélio Jargas, criador do txt2tags, foi criada a opção de chamada --strict (ou -r), que 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.
  6. Passou a ser possível definir o "nome" do post para uso na URL (por exemplo, "homem-morde-cachorro", que geraria uma URL como "http://url.do.blog/homem-morde-cachorro.html") explicitamente, e não apenas de forma automática a partir do título do post. Basta apresentar a definição em uma linha @@POSTNAME: ao final do arquivo txt de entrada.
  7. Incluída a chamada para plugins também ao final de um rebuild.
  8. Agora o Axe também tem índices cronológicos, por ano e mês. O arquivo archive.html é um índice geral dos meses, e os demais arquivos têm nome no formato archive-YYYY-MM.html.
  9. Agora o Axe gera automaticamente a cada rebuild completo ("-Rf") um sitemap (http://sitemaps.org/protocol.html), listando todos os posts (com prioridade 0.7), todos os índices, tags e archives. O sitemap não é informado automaticamente a nenhum site de busca, providencie isso (por exemplo, https://support.google.com/webmasters/answer/183669?hl=pt-BR) se desejar.
  10. Substituí o recurso de long options (exemplo: "--full") da função getopts() por uma função que a imita pobremente. Infelizmente vários dos provedores em que testei o Axe não instalam o PHP com suporte nativo a long options, só short options (tipo "-f").
  11. Criei a opção de chamada -h (ou --hereconf) para permitir chamar um Axe instalado em outro diretório, e fazê-lo ler o axe_config 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.
  12. Criei a opção -i (ou --indexonly) para ser usada junto com a -R (--rebuild). 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').
  13. Corrigido o bug que gerava feed RSS inválido quando um título de post recente incluía o caracter '&'.
  14. Corrigido o bug que gerava HTML inválido nos cabeçalhos quando o título de post incluía o caracter '"'.
  15. Várias outras correções de bugs e aperfeiçoamentos.

Agendando posts com o Axe

Atenção: a configuração dos recursos a seguir é opcional. Ela exige conhecimentos intermediários de administração de sistemas, e não deve ser efetuada sem suporte de um técnico habilitado e com conhecimento das configurações específicas do seu servidor.

O Axe tem seu próprio sistema de agendamento, que permite definir dia e hora em que o post deverá ir ao ar.

Ele é simples de ser usado, mas exige uma configuração prévia (apenas uma vez) na crontab1 do seu servidor.

Definindo dia e horário em que um post deve ir ao ar

Para definir dia e horário do post, acrescente ao final do arquivo TXT de entrada do seu post uma linha definindo a variável @@CRON, como a do exemplo a seguir:

@@CRON:26-22:34

No exemplo acima, o post iria ao ar às 22h34min do próximo dia 26. Não é possível indicar o mês: o formato adotado é DD-HH:MM.

O agendamento ocorre automaticamente no momento em que você pré-publica o post (ou seja, gera o draft dele, por meio do parâmetro -d).

Na prática, o ato de agendar corresponde simplesmente a o Axe criar, no diretório axe/drafts, uma versão especial do arquivo draft do seu post, cujo nome começará com o caracter @ seguido do dia e hora em que o post deve ir ao ar. Para o exemplo acima, o nome do arquivo draft gerado pelo Axe na pré-publicação poderia vir a ser axe/drafts/@26-22:34_titulo-do-post.php

Se você simplesmente renomear um draft existente para atender ao formato acima, o Axe também o tratará como um post agendado.

Configurando o agendamento na crontab

Para que o Axe chegue a perceber que há um post agendado aguardando na pasta axe/drafts pronto para ir ao ar, ele precisa ser chamado (usando o parâmetro -c) periodicamente pelo sistema cron do seu servidor web.

A configuração disso depende de cada provedor de hospedagem, mas a linha a seguir é a que eu uso na crontab do servidor do BR-Mac.org:

*/5 * * * * /home/brmac/br-mac.org/axe/axe.php -cq

O que ela faz é executar o comando mencionado ao final dela, a cada 5 minutos. Note que eu uni o parâmetro "-c" (obrigatório) ao "-q", que reduz as mensagens enviadas pelo Axe ao terminal (que, no caso de um cron bem configurado, serão enviadas ao seu e-mail). Assim, você só receberá e-mails do cron do Axe se ocorrer algum erro ao postar).

Para testar o recurso, você pode chamar o axe -c diretamente do seu terminal. Note, entretanto, que a configuração de ambiente de um programa chamado pelo cron não necessariamente é igual à de um programa chamado pelo terminal.

Um detalhe interessante: se houver mais de um post cujo horário de ir ao ar já chegou, o axe -c irá postar apenas um deles, deixando o outro para ser postado na próxima vez em que ele for chamado.

 
  1.  Busque junto ao seu provedor de hospedagem as informações sobre como acessar e administrar a crontab do seu servidor, e prossiga com cautela e contando com suporte especializado. Cada provedor oferece formas distintas de fazê-lo, e erros na operação podem colocar em risco outros serviços do seu sistema.

Como fazer um plugin para o Axe

Atenção: esta seção da documentação é reservada aos programadores interessados em criar expansões à funcionalidade do Axe por meio de plugins. Sua leitura não é necessária para outros usuários.

A interface de plugins do Axe ainda não chegou à sua especificação definitiva, portanto considere esta documentação como preliminar e sujeita a mudanças. Ela será ampliada e melhor detalhada quando a interface de plugins amadurecer, o que naturalmente ocorrerá dependendo do uso.

Os plugins para o Axe são armazenados no diretório axe/plugins e são chamados pelo Axe em vários momentos do processamento dos posts, índices e feeds.

De modo geral as interfaces já implementadas permitem que os seus plugins atuem como filtros de texto, recebendo um trecho de conteúdo ou do template que será usado para gerar uma página (por exemplo, o tema do rodapé de um índice de tags), aplicando a ele as modificações que desejar, e retornando ao Axe o texto original, com ou sem modificações.

No momento o Axe suporta plugins de templates nos seguintes contextos e subcontextos:

  • feed: header, item e footer
  • index: rebuild (chamado ao final de qualquer rebuild), header, post e footer
  • post: header, body, coverpreview e footer
  • blogparms: na inicialização do Axe, passa como parâmetro um array modificável com todos os parâmetros colhidos no axe_config.php.
  • postvars: após carregar um post para processamento, passa como parâmetro um array modificável com todos seus dados e metadados.

O plugin deve definir, para cada contexto em que deseja operar, uma função cujo nome é formado pela regra nomedoplugin_nomedocontexto. Exemplo: para um plugin chamado patrocinador.php, a função na qual ele deseja interferir no contexto post precisa se chamar patrocinador_post().

No momento, essa e todas as demais funções de plugins precisam ser definidas com suporte a receber 5 parâmetros, mesmo que não usem a todos. O primeira deles sempre é o conteúdo a modificar (e sempre retornar, em versão modificada ou não), e os demais dependem do contexto – por exemplo, no contexto post, o segundo parâmetro indicará o subcontexto (ver lista acima), e o terceiro indica o número sequencial (e não o ID!) do post sendo processado.

Como a interface ainda não está madura, não vou documentar quais os elementos de chamada de cada contexto e de cada subcontexto, e por enquanto você precisará pesquisar no código-fonte, procurando as chamadas à função aplica_plugins, e sempre desprezando o primeiro parâmetro dela, que nunca é passado ao plugin. Mas saiba que eles ainda podem mudar, a implementação atual é apenas a título precário.

Esqueleto do plugin exemplo.php:


<?php
/*

TITULO: Exemplo de plugin para modificar rodapés de índices e de posts

© 2013 Augusto Campos http://augustocampos.net/ (1.06.2013)

Licensed under the Apache License, Version 2.0 (the "License"); 
you may not use this file except in compliance with the License. 
You may obtain a copy of the License at 
http://www.apache.org/licenses/LICENSE-2.0 

Unless required by applicable law or agreed to in writing, software 
distributed under the License is distributed on an "AS IS" BASIS, 
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
See the License for the specific language governing permissions and 
limitations under the License.

*/


function exemplo_index($trecho,$template,$p2='',$p3='',$p4='') {
	if ($template=="footer") {
		// aplica modificações desejadas ao $trecho 
		// (que é template, e não conteúdo)
	}
	return $trecho;
}

function otherfeeds_post($trecho,$template,$c_items=0,$p3='',$p4='') {
	if (($template=="footer") && ($c_items < blogparm('NUMPOSTSCOVER'))) {
		// aplica modificações desejadas ao $trecho 
		// (que é template, e não conteúdo)		
	}
	return $trecho;
}

?>

Naturalmente, o plugin acima precisaria ser gravado como axe/plugins/exemplo.php.