aux/workflow/manpages.sh: Refactor how manpages and translations are made

I didn't like the previous version of aux/workflow/manpages.sh mainly for 2 reasons:
1. its CLI was terrible, ugly and fragile;
2. it mixed handling manpages and handling *translations*.

The first step was to split the translations part to a different file:
aux/workflow/l10n.sh.  Now it has the base logic for running po4a, and
can apply it to manpages.  It is useful for updating translated files
in other scenarios, such as catgets() message catalogs, markdown files,
etc.

After I used the venerable getopts to handle the command line
arguments, and give aux/workflow/manpages.sh a saner interface.

I disliked the fact that aux/workflow/manpages.sh still is being used
for the "install" and "uninstall" targets.  Before this file, the
canonical workflow of "make && make install/uninstall" was 100%
embedded within the Makefile itself.  But now the Makefile calls to an
external script for that.  This isn't a real cost, other than how
obvious the behaviour is for someone looking at the Makefile for the
first time.

I still chose to do it anyway, because there was already too many
things in the Makefile itself, and it was getting worse with time.  I
made sure to never cross the line of relying on an external tool for
the canonical "make && make install/uninstall", and even for
"make check".  Those all work without requiring any extra tool outside
what POSIX defines, such as "sed", "awk", etc.  Despite the cost of
adding this detour from the liner Makefile flow, I found it to be worth
it to call to the external script, as this script can now also be
shared across projects, and the customized Makefile be made simpler.

In other to remove the "-- $(do_subst)" horrendous hack, I chose to use
an inference rule for ".in" files, and remove the "$(do_subst)"
variable altogether.  Now all the files that need to go through sed
should end in ".in", and the Makefile will take care of producing it.
The upside is that this model is much better integrater into make
itself.

Addresses #task-9ee2bbc8-295f-52b7-4104-483869bad017.

1 files changed, 210 insertions, 0 deletions

diff --git a/doc/git-permalink.pt.1.in b/doc/git-permalink.pt.1.in
new file mode 100644
index 0000000..5b8ae4a
--- /dev/null
+++ b/doc/git-permalink.pt.1.in
@@ -0,0 +1,210 @@
+.\"*******************************************************************
+.\"
+.\" This file was generated with po4a. Translate the source file.
+.\"
+.\"*******************************************************************
+.TH GIT\-PERMALINK 1 @DATE@ "git\-permalink @VERSION@" "manual do usuário do git\-permalink"
+
+
+.SH NOME
+
+git\-permalink \- extensão Git para gerar links web permanentes (permalink) de
+arquivos de um repositório.
+
+
+.SH SINOPSE
+
+\fBgit\-permalink\fP [\fIOPÇÕES\fP] \fIARQUIVO\fP [\fINOLINHA\fP]
+
+
+.SH DESCRIÇÃO
+
+\fBgit\-permalink\fP usa o próprio Git para pegar a) o commit do \fIHEAD\fP e b) o
+\fIremote.origin.url\fP usando \fBgit\-config\fP(1), e opcionalmente c) um modelo
+de substituição de URL.  Então ele usa esses valores para construir o link
+para uma URL \fIpermanente\fP (permalink), com o commit incluso para garantir
+sua unicidade, e opcionalmente o número da linha selecionada.
+
+\fBgit\-permalink\fP depois usa o \fBxdg\-open\fP(1) para abrir a URL.
+
+.SH OPÇÕES
+
+.TP 
+\fB\-p\fP
+Somento imprime o link da URL web na saída padrão (STDOUT), não tenta
+abrí\-lo com \fBxdg\-open\fP(1) ou fazer qualquer coisa com ele.  Por padrão isso
+está desligado.
+
+.TP 
+\fB\-\-help\fP, \fB\-h\fP
+Mostra mensagem de ajuda.
+
+.TP 
+\fB\-\-version\fP, \fB\-V\fP
+Imprime o número da versão.
+
+
+.SH CONFIGURAÇÃO
+
+.SS "ORIGENS REMOTAS COM SUPORTE"
+
+A lista atual de origens remotas com suporte é:
+
+.RS
+.IP \(bu
+git.euandreh.xyz (onde o próprio git\-permalink está hospedado =p)
+.IP \(bu
+sourcehut
+.IP \(bu
+git.kernel.org
+.IP \(bu
+savannah
+.IP \(bu
+notabug
+.IP \(bu
+codeberg
+.IP \(bu
+bitbucket
+.IP \(bu
+pagure
+.IP \(bu
+gitlab
+.IP \(bu
+github
+.RE
+
+Mudanças para adição de mais sites de hospedagem de código são bem\-vindas!
+
+Veja
+.UR https://euandreh.xyz/git\-permalink/TODOs.html#task\-cebc5298\-17ad\-5c60\-dfa5\-a25b66433a3a
+#task\-cebc5298\-17ad\-5c60\-dfa5\-a25b66433a3a
+.UE
+para discussão e mais
+informações.
+
+.SS MODELOS
+
+Se você quiser configurar o modelo de substituição de URL de um projeto que
+não tem suporte a um tipo de origem remota você pode fazê\-lo com
+\fBgit\-config\fP(1).
+
+Há dois tipos de opções de configuração disponíveis:
+
+.TP 
+\fBgit\-permalink.template\-file\-commit\fP
+Um modelo de substituição de URL em que o nome do \fIarquivo\fP vem primeiro, e
+o \fIcommit\fP vem depois.  cgit usa esse tipo de URL, como em:
+
+.nf
+	https://git.euandreh.xyz/fallible/tree/%s?id=%s
+.fi
+
+Nesse exemplo, o nome do \fIarquivo\fP vem primeiro e o \fIcommit\fP vem só no
+final, depois do "id=".
+
+.TP 
+\fBgit\-permalink.template\-commit\-file\fP
+Um modelo de substituição de URL em que o \fIcommit\fP vem primeiro, e o nome
+do \fIarquivo\fP vem depois.  sourcehut usa esse tipo de URL, como em:
+
+.nf
+	https://git.sr.ht/~sircmpwn/scdoc/tree/%s/item/%s
+.fi
+
+Nesse exemplo, o \fIcommit\fP aparece primeiro no caminho da URL, e o nome do
+\fIarquivo\fP vem depois.
+
+.P
+Se nenhuma das duas opções for encontrada pelo \fBgit\-config\fP(1) e o
+\fBgit\-permalink\fP não consegue adivinhar a URL, ele termina com um erro.
+
+
+.SH EXEMPLOS
+
+Abre o arquivo \fIsrc/fold.c\fP de um projeto com a origem apontada para o
+\fIsourcehut\fP:
+
+.nf
+	$ git permalink src/fold.c 125
+	Abrindo https://git.sr.ht/~sircmpwn/ctools/tree/fbf17d92f5ed1c38983f73df912f051ad0f9ef2d/item/src/fold.c#L125
+.fi
+
+Gera um link das linhas 59 a 94 do arquivo \fInongnu/packages/clojure.scm\fP em
+um projeto hospedado no \fIgitlab\fP, mas somente o imprimie \fIsem\fP abrí\-lo com
+\fBxdg\-open\fP(1):
+
+.nf
+	$ git permalink \-p nongnu/packages/clojure.scm 59\-94
+	https://gitlab.com/nonguix/nonguix/\-/blob/c9d7f30bcbd3a6e3076e56a972c33963c73c4d58/nongnu/packages/clojure.scm#L59\-94
+.fi
+
+.P
+Configura um modelo de URL, e abre o arquivo \fIsrc/app_add.c\fP sem selecionar
+uma linha específica:
+
+.nf
+	$ git config git\-permalink.template\-file\-commit 'https://git.alpinelinux.org/apk\-tools/tree/%s?id=%s'
+	$ git permalink src/app_add.c
+	Abrindo https://git.alpinelinux.org/apk\-tools/tree/src/app_add.c?id=aeeb119fd8652c044cd5ceebce572b5c716914e3
+.fi
+
+.P
+Abre o arquivo \fI\-\-help\fP:
+
+.nf
+	$ git permalink \-\- \-\-help
+	Abrindo https://git.euandreh.xyz/non\-existent\-repository/tree/\-\-help?id=470a9fa9329495cfcbef8cc5e32e3a38d3c3103e
+.fi
+
+.SH "CÓDIGO DE SAÍDA"
+
+.TP 
+\fB0\fP
+Execução bem\-sucedida.
+
+.TP 
+\fB1\fP
+Sem suporte à origem remota.  Veja a lista de quais tem suporte em ORIGENS
+REMOTAS COM SUPORTE, e como adicionar origens customizadas a parteir de um
+model em MODELOS.
+
+.TP 
+\fB2\fP
+Argumentos inválidos.
+
+
+.SH "VEJA TAMBÉM"
+
+\fBgit\-config\fP(1)  \fBxdg\-open\fP(1)
+
+
+.SH AUTORES
+
+.MT eu@euandre.org
+EuAndreh
+.ME
+e colaboradores.
+
+
+.SH BUGS
+
+.IP \(bu
+Relate bugs na
+.MT ~euandreh/public\-inbox@lists.sr.ht
+lista de discussão
+.ME .
+Use o assunto "\f(CR[git\-permalink] BUG ou TASK:
+<descrição>\fR".
+.IP \(bu
+Veja os bugs
+.UR https://euandreh.xyz/git\-permalink/TODOs.html
+online
+.UE .
+.IP \(bu
+.UR https://euandreh.xyz/git\-permalink/
+Página inicial
+.UE .
+.IP \(bu
+.UR https://lists.sr.ht/~euandreh/public\-inbox?search=%5Bgit\-permalink%5D
+Comentários e discussões
+.UE .