A converter Ami Pro .SAM para Markdown para os Pipelines de Documentos

TL;DR

Escolha Markdown quando o conteúdo estiver a ser enviado para um repositório, um gerador de sites estáticos ou uma pipeline de texto. Markdown é pequeno, compatível com diffs e portátil: títulos, listas, tabelas e links sobrevivem, diagramas extraídos tornam-se ficheiros de imagem ligados, e equações podem manter o seu LaTeX. Combinado com Git, um ficheiro Ami Pro convertido torna-se passível de revisão em pull requests em vez de confiável apenas por fé. Converta com Ami Pro Converter.

Por que Markdown para documentos antigos

Docs-as-code mudou o que significa "ter documentação". O conteúdo num repositório obtém historial de versões, revisão de código, verificação automatizada de links e uma pipeline de construção. O conteúdo num formato binário proprietário não obtém nada disso — e um ficheiro .sam obtém menos do que nada, porque nenhuma ferramenta na cadeia consegue sequer lê-lo.

Converter para Markdown move décadas de material para o mesmo fluxo de trabalho que tudo o resto. Um procedimento de instalação de 1995 torna-se num ficheiro que podes comparar com a sua revisão de 2002, anotar num pedido de pull e publicar através do mesmo gerador de site estático que as notas de lançamento deste trimestre.

Markdown é também a escolha prática mais duradoura disponível. É texto simples com uma camada de convenção leve: legível sem qualquer software, analisável por dezenas de implementações e conversível para HTML, PDF, DOCX, ou qualquer outra coisa a pedido. Considerando que todo o problema começou com um formato de fornecedor que sobreviveu ao seu próprio fornecedor, essa portabilidade é o ponto central.

O que mapeia de forma limpa e o que não

Markdown é deliberadamente minimalista, o que é a sua força e o seu limite. A estrutura traduz-se bem; a apresentação não, e isso geralmente não importa porque a apresentação é a camada que si quer substituir de qualquer forma.

Cabeçalhos — os estilos Ami Pro do ficheiro .STY tornam-se em níveis de cabeçalho Markdown, proporcionando uma estrutura real ao documento
Listas — listas com marcadores e numeradas convertem-se em listas padrão Markdown, incluindo aninhamento
Ênfase — negrito e itálico correspondem diretamente; sublinhado não tem equivalente Markdown e normalmente torna-se ênfase
Tabelas — tabelas simples tornam-se tabelas de tubos; layouts complexos com células mescladas não podem ser representados e precisam de HTML como alternativa ou de uma nota
Imagens — diagramas WMF/EMF extraídos são gravados como ficheiros e referenciados com a sintaxe padrão de imagem
Equações — disponíveis em LaTeX para renderizadores capazes de matemática, ou como imagens ligadas quando não o são

As folhas de estilo são o que tornam os títulos possíveis

Este é o detalhe que decide se a conversão Markdown é útil ou inútil. Markdown não tem conceito de "Helvetica negrito de 16 pontos" — tem níveis de títulos. A única forma de um conversor saber que uma linha é um título de nível dois em vez de um parágrafo enfatizado é resolvendo o estilo do parágrafo em relação à folha de estilos .STY.

Com a folha de estilos presente, um documento convertido chega com uma hierarquia de títulos a partir da qual pode construir um índice e segmentar. Sem ela, obtém-se uma sequência plana de parágrafos com linhas ocasionalmente a negrito, e todos os benefícios acima desaparecem.

Portanto, antes de converter um ficheiro para um pipeline de documentos, verifique se os ficheiros .STY foram transferidos do servidor antigo. Leva um minuto e determina o resultado de todo o projeto.

Gestão de imagens num repositório

1. Decide onde os ativos residem

A maioria dos geradores de sites estáticos espera imagens num diretório dedicado ou colocadas ao lado da página. Escolha a convenção antes de converter para que esteja a mover ficheiros apenas uma vez, e não a renomear referências em milhares de ficheiros Markdown depois.

2. Ver tamanho do repositório

Os diagramas extraídos somam-se. Alguns milhares de documentos com figuras podem acrescentar centenas de megabytes a um repositório que anteriormente era apenas de texto. Considere o Git LFS ou mantenha os ativos em armazenamento de objetos e referencie-os através de URL.

3. Normalizar nomes de ficheiros

Os ficheiros legados estão cheios de nomes da era DOS, espaços e maiúsculas e minúsculas misturados. Normalize para nomes com hífen em minúsculas durante a transferência e mantenha uma tabela de mapeamento para que ainda possa rastrear uma página publicada até ao seu ficheiro original .sam.

4. Escolha uma estratégia de equação desde o início

Se o seu site renderizar matemática, use o LaTeX extraído e obtenha fórmulas nítidas, selecionáveis e pesquisáveis. Se não o fizer, use imagens renderizadas e aceite que a matemática não será pesquisável. Misturar ambos numa única coleção é a opção a evitar.

A rever milhares de ficheiros convertidos

Ninguém lê três mil ficheiros Markdown, mas o Git torna a revisão seletiva possível de uma forma que uma pasta com ficheiros DOCX não consegue. Aplicar a saída da conversão como um único grande commit numa branch, depois rever por padrão em vez de por ficheiro.

O Grep é a ferramenta principal aqui. Procure ficheiros suspeitosamente curtos, ficheiros sem qualquer cabeçalho, referências de imagens não resolvidas, marcação entre parênteses dispersa que indica uma lacuna de análise, e caracteres de substituição que indicam um problema de codificação. Cada uma dessas pesquisas revela uma classe de falha em segundos.

Adicione automação ao pipeline enquanto está nisso: um verificador de links para detetar referências internas quebradas, um validador de metadados se o seu gerador o exigir, e uma etapa de construção que falhe em caso de imagens em falta. Uma vez que esses passos sejam cumpridos, o ficheiro estará no mesmo regime de qualidade que a sua documentação mantida.

Onde Markdown é o alvo errado

Markdown deliberadamente não consegue expressar layouts de página complexos, e alguns documentos Ami Pro foram concebidos em vez de escritos — boletins informativos, formulários formatados, capas de relatórios com composição baseada em quadros. Forçar esses documentos para Markdown produz algo tecnicamente válido e praticamente inútil.

O mesmo se aplica a documentos cujo significado é legal e depende da apresentação exata: contratos executados, formulários assinados, avisos oficiais. Para esses, PDF é a saída honesta, e se deseja que sejam descobertos juntamente com o Markdown, converta para ambos e ligue o PDF a partir de um resumo curto Markdown.

Ser seletivo não é um compromisso. Um repositório de documentos cheio de Markdown limpos e estruturados, mais um conjunto ligado de PDFs para documentos que necessitam de layout fixo, é um resultado melhor do que uma pilha uniforme de conversões degradadas.

O que o Markdown dá a um arquivo antigo

Histórico de versões, revisão e comparações para documentos que nunca os tiveram
Publicável com o mesmo gerador de sites estáticos da documentação atual
Ficheiros de texto simples pequenos e portáteis, que sobrevivem a qualquer ferramenta
Estrutura de títulos adequada a índices e à segmentação para IA
Equações em LaTeX que continuam pesquisáveis em vez de se tornarem imagens

Documentos legados merecem ferramentas modernas

A diferença entre um ficheiro .sam e um ficheiro Markdown num repositório não é apenas uma mudança de formato. É a diferença entre conteúdo que ninguém pode inspecionar e conteúdo que participa na revisão, pesquisa e publicação automática como tudo o resto que a sua equipa escreve.

Confirme as folhas de estilo, decida as suas convenções de ativos e equações antes de começar, converta o ficheiro de uma só vez e revise usando grep em vez de ler. Depois, envie-o pelo mesmo pipeline que o resto dos seus documentos.