Disponibilizando meus posts do blog como páginas de manual do Linux

Disponibilizando posts do blog como páginas de manual do Linux

• Computadores Linux vêm com páginas de manual pré-instaladas que explicam como usar determinados comandos.
• É possível ler uma página de manual digitando man <command> no terminal.
• Alguns softwares de linha de comando instalados também adicionam páginas de manual.
• As páginas de manual do Linux são formatadas usando a sintaxe roff.
• roff foi o primeiro software de composição tipográfica em linha de comando para Unix, desenvolvido no Bell Labs.
• O artigo explora a ideia de disponibilizar posts de blog como páginas de manual do Linux.

Projeto do sistema: negociação de conteúdo

• A ideia é permitir que usuários solicitem uma versão roff de um post do blog por meio de negociação de conteúdo HTTP.
• Negociação de conteúdo é uma parte do HTTP que permite fazer requisições especificando o formato do arquivo.
• Isso é feito usando cabeçalhos HTTP para solicitar ao servidor conteúdo em um formato específico.
• É possível rotear requisições de usuários que enviam o cabeçalho Accept.
• Ao solicitar um documento text/roff, o servidor pode retornar uma página de manual que pode ser aberta com o comando man.

Escrevendo a página de manual

• Como páginas de manual usam a sintaxe roff, é necessário ter o post do blog nesse formato.
• O site foi atualizado para gerar uma página man para cada post do blog.
• Para gerar a página de manual, o nome de domínio é definido como cabeçalho, e são criadas cinco seções: título, autor, data de publicação, conteúdo do post e URL do post.
• O conteúdo original está em Markdown e, às vezes, o espaçamento pode não aparecer corretamente no manual.
• Markdown é mais fácil de ler e perde menos informação do que HTML.

Solicitando a página de manual

• É possível solicitar o formato roff de um post do blog com o seguinte comando:

  curl -sL -H "Accept: text/roff" https://jamesg.blog/2024/02/28/programming-projects/ > post.page && man ./post.page
  

• O resultado pode ser aberto como uma página de manual do Linux.
• Diferentemente de quando o navegador solicita a versão HTML da página, o comando curl solicita a versão text/roff.
• Algumas linhas foram adicionadas à configuração do NGINX para mudar a forma como o servidor responde quando text/roff é solicitado.
• No arquivo de configuração do NGINX, é declarada uma variável que define um sinalizador quando um tipo de conteúdo específico é identificado.
• Na configuração do site no NGINX, é usado um código que trata a requisição de forma diferente quando uma página roff é solicitada.
• Agora é possível ler os posts do blog deste site como páginas de manual do Linux.
• O artigo também explora como usar negociação de conteúdo no NGINX e como as tecnologias de composição tipográfica evoluíram.

Opinião do GN⁺

• Este artigo pode chamar a atenção de entusiastas de tecnologia ao apresentar uma forma original de oferecer conteúdo de blog por meio de páginas de manual do Linux.
• Ele fornece um exemplo prático de negociação de conteúdo com NGINX, oferecendo informações úteis para administradores de servidores web e desenvolvedores.
• Sob uma perspectiva crítica, o formato Markdown pode nem sempre ser exibido corretamente em páginas de manual, então pode ser necessário trabalho adicional para melhorar isso.
• Outros projetos com funcionalidade semelhante incluem ferramentas como o pandoc, que oferecem conversão entre vários formatos de documento.
• Ao adotar essa técnica, é preciso considerar as necessidades dos usuários e a compatibilidade.
• A principal vantagem dessa abordagem é oferecer conteúdo web existente de uma forma familiar para usuários de Linux; a desvantagem é que ela pode trazer manutenção extra e problemas de compatibilidade.