Bagaimana cara mengubah halaman manual Linux menjadi HTML tanpa menggunakan groff?


11

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).


Kenapa tidak kamu gunakan troff? Ini gratis.
schily

Saya tidak tahu caranya, saya belajar cara menggunakan groff dengan membaca beberapa jawaban di situs ini dan situs terkait. Jika Anda menulis jawaban yang melibatkan troff, saya mungkin akan menerimanya, tergantung pada kualitas jawaban lain untuk pertanyaan ini.
BH2017

mengapa tidak mengirimkan laporan bug ke sabayon dan meminta mereka untuk memperbaiki bug mereka?
cas

@cas Tautan pertama (masalah render PNG) adalah ke laporan bug Sabayon yang saya ajukan sekitar waktu saya mengajukan pertanyaan ini.
BH2017

coba temukan dan perbaiki sumber warning: can't find font `b'pesan - yang mungkin menjadi penyebabnya karena file png yang dibuat cenderung hanya berupa teks dalam format grafis. mungkin paket font yang hilang yang perlu diinstal.
cas

Jawaban:


10

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:


Ah, saya harus mengklarifikasi saya tidak hanya tertarik pada nama program, saya tertarik persis bagaimana menggunakannya untuk mengkonversi halaman manual ke HTML. Jadi tolong pilih setidaknya salah satu dari program ini dan tunjukkan kepada saya bagaimana mengkonversi halaman manual ke HTML dengan itu.
BH2017

Terima kasih atas hasil editnya, jauh lebih baik! Saya punya beberapa pertanyaan. Mengapa Anda mengarahkan stderr ke file html dalam man2htmlcontoh ini? Dan mengapa mengarahkan ke file di /var/www/html? Tidak perlu server web, cukup arahkan kembali ke file lokal dan Anda dapat mengarahkan browser Anda ke sana. Juga, apakah Anda memeriksa man2htmloutput Anda ? Saya mencobanya di Arch saya dan tidak menghasilkan output yang diformat.
terdon

Tidak perlu mengarahkan ulang stderr, abaikan itu :-). Saya telah mengarahkannya ke / var / www / html sehingga saya dapat melihat hasilnya selama pengujian saya (saya menggunakan sistem jarak jauh melalui ssh). Anda tidak perlu - menggunakan browser secara lokal berfungsi dengan baik. Saya telah memeriksa keduanya - dan mereka terlihat OK di sistem saya. Tidak memeriksa apakah mereka dapat menghasilkan PNG (atau apa pun masalahnya dengan Arch).
Criveti Mihai

Saya suka jawaban ini, saya pikir saya akan menerimanya, tetapi ada satu masalah terakhir dengan jawaban ini. Lihat Sabayon menggunakan halaman manual dalam .bz2format alih-alih .gz, jadi bisakah Anda menulis ulang jawaban Anda? Seperti memodifikasi baris zcat dengan yang akan berfungsi dengan halaman manual yang dikompresi bzip2.
BH2017

man2html membutuhkan output nroff dan tidak bekerja di input trodd Contoh Anda salah.
schily

6

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

masukkan deskripsi gambar di sini

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


Proyek ini telah diubah namanya menjadi mandoc.
Franklin Yu

5

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.


1

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.


Ah, Anda mengalahkan saya untuk itu! Saya baru saja menginstal heirloom-doctoolsjuga. Harus mengutak-atik mk.config:-).
Criveti Mihai

0

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).


Seperti disebutkan sebelumnya: man2htmlmengambil output nroff sebagai inputnya, Anda karenanya tidak dapat memberikan file sumber halaman manual sebagai input.
schily

1
@shily Itu tergantung yang man2htmlkamu bicarakan.
Kaz

> 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. Lihat di sini: kylheku.com/cgit/man/log
Kaz
Dengan menggunakan situs kami, Anda mengakui telah membaca dan memahami Kebijakan Cookie dan Kebijakan Privasi kami.
Licensed under cc by-sa 3.0 with attribution required.