Come creare l'ingresso manuale per il pacchetto Deb

Question

Dove scrivo una voce manuale durante la creazione di un pacchetto DEB?C'è qualche regola di formattazione / migliore pratica da rispettare?

Sono molto nuovo alla creazione del pacchetto Deb.Seguendo alcuni tutorial, ho appena creato un pacchetto che installa / esegue bene, quindi ora vorrei scrivere una documentazione in modo che man myFancyPackage restituisca qualcosa invece di nessuna voce manuale per MyFancypackage .

Sfortunatamente nessuno dei tutorial che ho trovato parlare della creazione manuale.

Answer 1

Ci sono molti metodi per costruire un pacchetto Debian, ma l'attuale "migliore pratica" è utilizzare gli strumenti forniti da Debhelper. Nel caso delle pagine man, c'è uno strumento denominato dh_installman (leggi il suo Manpage ) che viene chiamato automaticamente da dh. Se hai utilizzato dh_make o simile per creare un modello per il pacco, allora un'invocazione dh sarà nel file debian/rules.

dh_installman funziona leggendo il file debian/manpages o debian/nameofyourpackage.manpages. Questo file ha un elenco di percorsi che puntano alle pagine dell'uomo del pacco. I percorsi sono relativi alla radice del pacco. Qui hai un Esempio di un pacchetto reale. Quindi, questo programma installerà correttamente le pagine dell'uomo nella directory giusta.

Così, per riassumere, devi solo creare il debian/package.manpages e riempirlo con i percorsi alle pagine dell'uomo. Questi percorsi devono essere relativi alla radice del pacco. Se tu, il packager, stai scrivendo le pagine dell'uomo, devono essere inserite nella directory Debian/.

Answer 2

Le pagine dell'uomo sono state tradizionalmente composte in un linguaggio di composizione chiamato roff utilizzando un pacchetto macro chiamato an (quindi la riga di comando era roff -man, SIC) ma poche persone scrivono più roff.

Ci sono vari formati di documentazione SGML e XML che hanno la capacità di generare sorgenti di pagine man, anche se in questo giorno ed età, Markdown sta probabilmente guadagnando terreno come de facto standard per la nuova documentazione. Il top google hit per me è https://github.com/remarkjs/remark-man Anche se ti suggerisco sicuramente di guardare pandoc.

# NAME

Markdown - popular text markup language

# SYNOPSIS

man markdown

# DESCRIPTION

This is a popular lightweight syntax
to generate styled text from an
editor-friendly text source.
It is used on [Stack Overflow][1],
[Github][2], and increasingly on
blogging and authoring platforms.

  [1]: https://stackoverflow.com/
  [2]: https://github.com/

.

menzionerò anche Formato POD , che ha una lunga storia nella comunità perl e molte caratteristiche in comune con formati leggeri più recenti più recenti. A meno che tu non abbia altri motivi per piacerti, non lo sceglierei per una nuova documentazione, ma è stato moderatamente popolare anche per quanto riguarda il mondo perl quando è stata una delle uniche opzioni con un semplice formato sorgente leggibile dall'uomo, ovvio Semantica e un attrezzo e un ecosistema di supporto versatile e ben tenuto. Alcuni probabilmente direbbero che è ancora.

=head1 NAME

Pod::Example - Example POD document

=head1 SYNOPSIS

pod2man thisdoc.pod >thisdoc.1

=head1 DESCRIPTION

Lightweight syntax for subheads,
hyperlinks, indented lists,
and not much else.
Natively supported in Perl source files
to facilitate a crude form of
literate programming.

.