Saya ingin mengonversi beberapa halaman manual Linux ke HTML tanpa menggunakan groff. Prasangka saya terhadap groff adalah karena beberapa masalah rendering PNG itu memberi saya yang tampaknya dilokalisasi ke Sabayon (karena masalah ini tampaknya tidak terjadi pada VM VirtualBox saya untuk distro lain). Saya menyadari ini adalah bug, tetapi solusi tampaknya tidak dalam waktu dekat jadi saya ingin bertanya apakah ada cara lain untuk mengubah halaman manual Linux ke HTML. Menggunakan halaman HTML di http://linux.die.net/man bukan solusi yang dapat diterima karena beberapa halaman manual yang saya minati tidak ada di sana (misalnya, emerge(1)tidak ada di sana).

Ada banyak alternatif seperti roffit , troff , man2html . Ada juga peramban manpage online berbasis perl, seperti manServer .

Favorit saya adalah pandoc, meskipun sayangnya tampaknya tidak mendukung input ROFF secara default (meskipun Anda mungkin dapat menggunakannya jika Anda perlu untuk menghubungkan beberapa filter transformasi bersama.

contoh man2html:

zcat /usr/share/man/man1/dd.1.gz \ 
    | man2html \
    | sudo tee /var/www/html/dd.html

contoh roffit:

git clone git://github.com/bagder/roffit.git
cd roffit
zcat /usr/share/man/man1/dd.1.gz \
    | perl roffit \
    | sudo tee /var/www/html/dd-roffit.html

Alat lainnya:

• troffcvt melakukan hal yang sama.
• The 'real' troff- Akan mencoba http://heirloom.sourceforge.net/doctools.html . Saya menduga schily memiliki OpenSolaris dan teman-teman dalam pikiran :-).

Bit pertama ini adalah rip tak tahu malu dari situs web resmi :

mandocadalah seperangkat alat yang menyusun mdoc, roffbahasa makro pilihan untuk halaman manual BSD, dan man, bahasa historis utama untuk manual UNIX. Ini kecil, ISO C, berlisensi ISC, dan cukup cepat. Komponen utama dari toolset adalah mandocprogram utilitas, berdasarkan pada libmandockompilator validasi, untuk memformat output untuk terminal UNIX (dengan dukungan untuk karakter berkarakter luas) , XHTML, HTML, PostScript, dan PDF.

mandocsebagian besar telah dikembangkan di OpenBSD dan merupakan proyek OpenBSD dan BSD.lv. Kami berusaha untuk mendukung semua sistem operasi bebas yang tertarik, khususnya FreeBSD, NetBSD, DragonFly, illumos, Minix 3, dan GNU / Linux, serta semua sistem yang menjalankan sistem pkgsrcpaket portabel. Untuk mendukung mandocpengembangan, pertimbangkan untuk menyumbang ke yayasan OpenBSD.

pacmanmemberi tahu saya mdocmlukuran paket yang saya instal secara lokal adalah 3.28mb, dan itu termasuk /usr/binbinari yang terletak di bawah ini :

/usr/bin/demandoc
/usr/bin/makewhatis
/usr/bin/mandoc
/usr/bin/mapropos
/usr/bin/mman
/usr/bin/mwhatis

Dengan itu saya bisa melakukan:

mman -Thtml mman >/tmp/html
firefox file:///tmp/html

Anda dapat menerapkan stylesheet Anda sendiri sesuka Anda. Semua dokumentasinya online , juga. Dan semua itu, seperti yang saya pikirkan, dikompilasi mandocjuga.

Pertama, harus dicatat bahwa ada lebih dari satu program yang disebut man2html.

Salah satu utilitas yang disebut man2htmladalah program C yang aslinya ditulis pada akhir 1990-an oleh Richard Verhoeven di Eindhoven University of Technology pada akhir 1990-an. Program ini memiliki internal yang cukup unik. Namun, ini memiliki keuntungan bahwa ia bekerja dengan sumber halaman manual, daripada troffatau nroffoutput. Program ini ditambahkan ke man suite Frederico Lucifredi.

Program ini memahami semantik mandan mandocmakro, dan menampilkan struktur HTML yang masuk akal. Misalnya ketika Anda menggunakan paragraf indentasi, seperti ini:

Kata .IP
Definisi dari
kata.
.RS

program akan mengeluarkan daftar definisi HTML.

Saya memelihara satu halaman manual yang sangat besar (sebagian besar megabyte sumber, dan hampir 400 halaman, ketika dikonversi ke ukuran huruf PDF oleh groff):

$ ls -l txr.1
-rw-rw-r-- 1 kaz kaz 980549 3 Jan 11:38 txr.1

Ketika saya perlu mengonversikan ini ke HTML, sekitar lima tahun yang lalu, satu-satunya hal yang saya temukan yang melakukan pekerjaan yang masuk akal adalah man2htmlprogram C, ditambah post-processing outputnya menjadi "season to taste".

Akhirnya, saya menginginkan dokumen HTML yang jauh lebih berkualitas, jadi saya mulai menulis troffmakro. Keterbatasan program C menjadi sangat jelas, jadi saya memotongnya. Di situs git saya, Anda dapat menemukan repo git dengan 30 tambalan ke man2html . Tambalan ini memperbaiki sejumlah bug, dan meningkatkan program dengan kemampuan yang jauh lebih baik untuk menafsirkan makro truf, kondisional, loop, dan konstruksi lainnya. Saya juga menambahkan M2register dengan mana Anda dapat menulis kode yang mendeteksi bahwa itu berjalan di bawah man2htmldan kondisional dapat melakukan beberapa hal secara berbeda (gulir ke bawah untuk contoh). Juga, saya menambahkan .M2SSperintah yang memungkinkan Anda memancarkan bagian header HTML kustom.

Halaman besar saya diinangi di sini . Ini diproduksi dengan man2html, setelah diproses oleh genman.txrprogram saya , yang mengatur ulang bagian, dan menambahkan hyper-link di seluruh dokumen. Itu juga menulis ulang tautan internal dalam daftar isi menjadi URL yang stabil (berdasarkan hashing daripada enumerasi acak) dan membuat daftar isi dapat dilipat melalui beberapa Javascript.

Perintah persis yang digunakan oleh saya Makefile:

man2html txr.1 | ./txr genman.txr -> txr-manpage.html
tbl txr.1 | pdfroff -man --no-toc -> txr-manpage.pdf

Untuk contoh tentang bagaimana output berbeda secara kondisional antara HTML dan nroffkita dapat melihat bagian dari manoutput:

       9.19.4 Macro defstruct

       Sintaksis:

                (defstruct {<name> | (<name> <arg> *)} <super>
                   <slot-specifier> *)

              Makro defstruct mendefinisikan jenis dan register struktur baru
              di bawah <name>, yang harus menjadi simbol yang bisa diikat, menurut
              fungsi bindable. Demikian juga, nama setiap <slot> harus
              juga menjadi simbol yang bisa diikat.

Di atas, perhatikan bagaimana parameter dilambangkan <angle> <brackets>. Dalam versi HTML, mereka muncul dalam huruf miring .

Bagian sintaks muncul di kode sumber seperti ini:

.coNP Macro @ defstruct
.synb
.mets (defstruct >> {name | >> (name << arg *)} <super
.mets \ \ << slot-specifier *)
.sejak itu

yang semuanya makro kustom didefinisikan dalam dokumen yang sama. Di bawah .mets, < bberarti badalah variabel meta-sintaksis. >> a bberarti aadalah sintaksis konkret, di sebelahnya adalah meta-sintaksis btanpa ruang intervensi, dan <> a b cberarti badalah meta-sintaksis yang berderak antara adan cliteral.

Versi perbaikan saya man2htmlmemahami makro yang cukup rumit yang mengimplementasikan konvensi markup ini.

Juga, perhatikan bagaimana manual memiliki nomor bagian: itu semua dilakukan oleh kode troff, yang man2htmlmengerti.

Sejak OpenSolaris dibuat tersedia sebagai OSS, ada yang gratis troff.

Satu set sumber porting ada di sini:

http://heirloom.sourceforge.net/doctools.html

tetapi Heirloom adalah proyek mati sejak aprox. 2007. Anda mungkin ingin memeriksa

https://github.com/nt-roff/heirloom-doctools

di mana beberapa orang melanjutkan proyek pusaka mati.

Bersama dengan man2html, troff memungkinkan Anda untuk membuat halaman manual html yang bagus secara otomatis.

Lihat misalnya halaman manual SchilliX:

http://schillix.sourceforge.net/man/

dengan Schily Bourne Shell:

http://schillix.sourceforge.net/man/man1/bosh.1.html

Saya senang dengan ini dan dengan opsi yang tepat, Anda bisa ditautkan halaman manual ke dokumentasi lain dari grup yang sama. Saya menggunakan mis perintah ini:

soelim sh.1 | tbl | nroff -u1 -Tlp -man - | col -x | \
                        (sed -e 's/XXX/sh.1/g' ../conf/pre.html; \
                        man2html  -cgiurl '../man$section$subsection/$title.$section$subsection.html' -compress -nodepage; \
                        cat ../conf/post.html) | \
                        egrep -v 'HTML|BODY'> sh.1.html

itu adalah bagian dari sistem file make di alat schily. Perhatikan file ../conf/pre.htmldan ../conf/post.htmldari sistem makefiles schily yang diperlukan untuk judul dan lain-lain. Anda mungkin ingin mengubah ini empat kebutuhan Anda.

Yang disempurnakan man2thmladalah bagian dari alat schily (lihat bagian bawah boshhalaman manual).

BTW: informasi lucu: seluruh troffkode sumber ditambah semua sumber untuk semua program pembantu seperti soelim,, tbl... ditambah mansumber program hanya setengah dari kode yang Anda butuhkan untuk mandocprogram dan mandochanya memiliki tbldukungan yang sangat terbatas yang membuat sebagian besar Solaris tidak bisa halaman.

Jika Anda memerlukan dukungan untuk mandocsumber troff yang diformat dari FreeBSD dan sejenisnya, saya membuat satu set makro mandoc yang cocok untuknya troff. Periksa sumber SchilliX di: https://sourceforge.net/p/schillix-on/schillix-on/ci/default/tree/usr/src/cmd/troff/troff.d/tmac.d/ Kode yang dimaksud ada dalam file andocdan doc*.

Sumber manprogram di SchilliX-ON telah diubah untuk memanggil nroff -mandocalih-alih nroff -man.

Masalah OP dengan file PNG cocok dengan pengalaman saya menggunakan groff untuk halaman manual xterm dan dokumentasi urutan-kontrol. Masalahnya adalah bahwa groff berusaha membuat tabel sebagai gambar yang dipotong dari file PDF, dan itu telah bermasalah selama beberapa tahun. Walaupun saya telah menggunakan skrip Perl man2html sejak 1990-an untuk dokumentasi ncurses, untuk program lain saya merasa lebih mudah untuk menghasilkan file ad hoc html dan pdf menggunakan groff. File PDF berfungsi dengan baik; file html tidak.

Pada saat yang sama, skrip Perl memiliki masalah sendiri.

Karena tidak ada yang hilang (dan karena alternatif yang disarankan belum menjadi perbaikan, karena menambah ketergantungan atau memperkenalkan batasan lain), saya menyelesaikan masalah dengan melakukan perbaikan pada man2html (di atas semua yang telah saya buat selama beberapa tahun) dan menambahkan opsi skrip konfigurasi baru untuk setiap program untuk memungkinkan menggunakan groff sebagai manpage default ke html converter, tetapi menggunakan man2html ketika saya mengatur opsi. Setelah melakukan ini, saya menghapus semua file html yang dihasilkan groff tahun ini dari situs web saya . Ada halaman "man2html" di situs web yang mendokumentasikan ini; skrip yang sebenarnya tersedia di halaman skrip aneka saya .

Beberapa saran dan komentar tampaknya tidak memperhatikan bahwa ada (setidaknya) dua program bernama man2html:

• skrip Perl oleh Earl Hood (ditautkan oleh @ criveti-mihai ), dan
• sebuah program C yang awalnya ditulis oleh Richard Verhoeven (dan diasumsikan dalam contoh yang diberikan oleh @ criveti-mihai ).

Program C melakukan pemformatannya sendiri, tidak bergantung pada nroff / groff / apa pun. Ia dapat membaca halaman manual dari input standar, atau sebagai file aktual (antara lain - lihat halaman manualnya ). Diberikan halaman manual sintaksis nroff "foo.1", Anda dapat memformatnya menggunakan salah satu dari perintah ini:

man2html - <foo.1 >foo.1.html
cat foo.1 |man2html - >foo.1.html
man2html foo.1 >foo.1.html

Skrip Perl membaca halaman manual yang diformat , misalnya, dari nroff(yang untuk pertanyaan OP adalah pembungkus untuk groff). Anda bisa menggunakannya seperti ini:

nroff -man foo.1 |man2html >foo.1.html

Saya menyelidiki menggunakan program C sebagai alternatif untuk skrip Perl, tetapi membuangnya karena

• itu tidak melakukan pekerjaan dengan baik memformat output. Dalam pemeriksaan cepat dengan file terminfo.5 ncurses, saya bisa melihat kesalahan dalam format output.
• program C memiliki gagasan bawaan tentang makro halaman manual yang tidak mencakup berbagai kasus (termasuk menulis makro baru) yang saya perlukan untuk halaman manual di situs web saya.

Kebetulan, ia menangani beberapa pengalihan yang digunakan dalam file ini (yang merupakan masalah dengan warisan troff - alasan instruksi instalasi ncurses menyarankan menggunakan groff selama 20 tahun terakhir).