Bagaimana cara saya menulis halaman manual? [Tutup]

16

Bagaimana cara saya menulis halaman manual?

Di mana saya dapat menemukan referensi semua kode pemformatan?

Apakah ada tutorial bagus tentang cara menulis halaman manual?

Apa cara paling nyaman untuk menulis halaman manual? Haruskah saya memasukkannya langsung ke editor teks? Apakah ada editor WYSIWYG? Atau haruskah saya menulisnya dalam format yang berbeda dan kemudian mengonversi?

Aturan apa yang harus diikuti oleh halaman manual yang baik?

documentation

— amarillion
sumber

Pertanyaan ini tampaknya terlalu luas. Itu hanya berhasil menarik banyak jawaban hanya tautan dan beberapa pendapat yang tidak didukung.

— 200_sukses

man man, man groff.

— Jenny D

13

Berikut adalah beberapa halaman web yang akan membantu Anda memulai:

Beberapa alat yang berguna:

— Dijeda sampai pemberitahuan lebih lanjut.
sumber

6

Ada alat untuk menulis halaman manual yang memotong pemformatan troff. manual adalah bahasa yang kecil, dibatasi dengan baik, dan mudah ditargetkan.

Dua alat yang populer adalah:

xmltoman , bahasa xml kecil dan terstruktur dengan baik yang dapat menghasilkan halaman manual dan html. Ini digunakan oleh proyek Lennart Poettering, syrep dan pulseaudio misalnya .
asciidoc , digunakan oleh git misalnya .

yodl dan zoem tampaknya merupakan format bagus lainnya di ruang ini.

Semua dalam semua, saya akan merekomendasikan xmltoman karena ini adalah dsl spesifik halaman manual yang akan memandu Anda dengan cermat.

— Tobu
sumber

"dsl" == "bahasa khusus domain"?

— Dijeda sampai pemberitahuan lebih lanjut.

ya (da. si. 15 karakter.)

— Tobu

1

Pilihan bagus lainnya adalah ronn , yang membaca bahasa marka teks Markdown yang lebih banyak digunakan.

— poolie

5

Saya telah menulis artikel blog yang agak luas tentang topik ini, yang dapat Anda temukan di sini:

http://2buntu.com/articles/1034/how-to-write-a-manpage/

— Nathan Osman
sumber

4

Akan sangat membantu jika Anda setidaknya dapat meringkas artikel di sini - tautan saja tidak ada gunanya begitu halaman yang ditautkan bergerak atau menghilang.

— Caleb

Saya tidak setuju dengan Caleb. Ini webnya. Web didasarkan pada tautan, dan stackexchange tidak membawa pengecualian khusus untuk ini. Menyalin konten kontraproduktif. Apapun hal buruk bisa terjadi bahwa halaman atau dokumen juga dapat terjadi pada ini satu. Kami tidak dapat menyimpan salinan semua konten yang tergores hanya karena sisa web mungkin hilang. (Tinggalkan pekerjaan itu ke situs-situs seperti mesin wayback).

— Kaz

Kaz, Anda mungkin tidak setuju, tapi komentar Caleb jelas merupakan praktik terbaik ServerFault.

— MadHatter

2

Saya tidak tahu ide atau tutorial apa pun, tetapi Anda bisa mulai dengan menyalin halaman manual yang ada dan memodifikasinya sesuai dengan kebutuhan Anda.

Untuk referensi bahasa groff dengan makro MAN (yang digunakan oleh halaman manual), lihat halaman manual groff_man , atau baca secara online di sini

— Dan Andreatta
sumber

2

Lihatlah proyek ronn . Ini adalah penurunan harga untuk pembuatan halaman manual. Itu juga dapat menghasilkan halaman manual dalam html, seperti ini .

Saya suka ide untuk menulis semua dokumentasi perangkat lunak saya dalam satu format. Penurunan harga IMO adalah pilihan yang baik

— Bruno Polaco
sumber