Menulis Halaman Manual di Linux

Saat kita menulis satu program yang akan dishare ke publik, kita sebaiknya membuat satu halaman manual untuk memberikan informasi detail tentang program kita tersebut. Di Linux, manual ini biasanya akan tersimpan di direktori /usr/share/man atau /usr/local/man (lihat dengan perintah manpath). Kita mungkin sudah tidak asing dengan perintah, misalnya man ls, yang mungkin akan membaca file manual ls.1 (baik terkompress maupun tidak) dari direktori MANPATH. Sekarang kita akan mencoba membuat file manual dan menginstallnya ke MANPATH.

Kalau kita coba jalankan man ls mungkin akan tampil keluaran berikut:

LS(1)       User Commands                                    LS(1)

NAME
       ls - list directory contents

SYNOPSIS
       ls [OPTION]... [FILE]...

DESCRIPTION
       List information about the FILEs (the current directory by default).  
       Sort entries alphabetically if none of -cftuvSUX nor --sort.

       Mandatory arguments to long options are mandatory for short options too.

       -a, --all
              do not ignore entries starting with .
...


Umumnya isi yang ada di manual adalah:

  • Header
  • Name
  • Synopsis
  • Description
  • Options
  • Files
  • See also
  • Bugs
  • Authors

Format Manual

Dokumen manual diformat di Linux dengan utility groff. Berikut template manual yang memuat option, command, dan macro (diambil dari [1] dengan modifikasi):

.\" This is a simple manual template
.TH MYAPP 1
.SH NAME
Myapp \- A simple demonstration application that does very little.
.SH SYNOPSIS
.B myapp
[\-option ...]
.SH DESCRIPTION
.PP
\fImyapp\fP is a complete application that does nothing useful.
.PP
It was written for demonstration purposes.
.SH OPTIONS
.PP
It doesn't have any, but let's pretend, to make this template complete:
.TP
.BI \-option
If there was an option, it would not be \-option.
.SH RESOURCES
.PP
myapp uses almost no resources.
.SH DIAGNOSTICS
The program shouldn't output anything, so if you find it doing so there's
probably something wrong. The return value is zero.
.SH SEE ALSO
The only other program we know with this this little functionality is the
ubiquitous hello world application.
.SH COPYRIGHT
myapp is Copyright (c) 2003 Wrox Press.
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
.SH BUGS
There probably are some, but we don't know what they are yet.
.SH AUTHORS
Neil Matthew and Rick Stones

Beberapa penjelasan yang saya mengerti:

  1. Baris dengan awalan . (titik) adalah sebuah request
  2. Baris comment diawali dengan .\”
  3. Macro header mempunyai format: .TH {APPLICATION} {SECTION} {OTHERS}
    Penomoran section yang menunjukkan tipe halaman manual:

    0 File header (biasanya ada di /usr/include)
    1 Program Executable atau skrip shell
    2 System calls (Fungsi yang disediakan oleh kernel)
    3 Library calls (Fungsi dalam library program)
    4 Special files (Biasanya ditemukan di /dev)
    5 Format file dan konvensinya, misalnya /etc/passwd
    6 Game
    7 Miscellaneous (termasuk paket macro dan konvensinya), misalnya man(7), groff(7)
    8 System administration commands (Biasanya hanya untuk root)
    9 Kernel routines [Non standard]
  4. Tentang formatting:
    .B : Bold teks, satu baris
    .I : Underline teks, satu baris
    \fB : Perubahan font menjadi format bold
    \fI : Perubahan font menjadi format underline
    \fR : Perubahan font menjadi format regular
    \- : Karakter –

Walaupun template di atas sudah mencukupi, namun untuk melihat referensi lebih lengkap tentang formatting dan isi dokumen manual , bisa dilakukan dengan perintah man 7 groff atau info groff.

Untuk menginstall manual tersebut, entry install-man dapat dimasukkan dalam skrip Makefile:

MANDIR=/usr/share/man

install-man:
	for i in $(srcdir)/*.[1-8] ; do \
		ext=`echo $$i | sed 's/.*\.//'`; \
		mkdir $(DESTDIR)$(MANDIR)/man$$ext/; \
		install -m 644 $$i $(DESTDIR)$(MANDIR)/man$$ext/; \
	done
	
	

Jika perintah man myapp dijalankan, maka akan keluar output:

MYAPP(1)                                                              MYAPP(1)

NAME
       Myapp - A simple demonstration application that does very little.

SYNOPSIS
       myapp [-option ...]

DESCRIPTION
       myapp is a complete application that does nothing useful.

       It was written for demonstration purposes.

OPTIONS
       It doesn't have any, but let's pretend, to make this template complete:

       -option
              If there was an option, it would not be -option.

RESOURCES
       myapp uses almost no resources.

DIAGNOSTICS
       The program shouldn't output anything, so  if  you  find  it  doing  so
       there's probably something wrong. The return value is zero.

SEE ALSO
       The  only  other program we know with this this little functionality is
       the ubiquitous hello world application.

COPYRIGHT
       myapp is Copyright (c) 2003 Wrox Press.  This program is free software;
       you  can  redistribute  it  and/or modify it under the terms of the GNU
       General Public License as published by the  Free  Software  Foundation;
       either version 2 of the License, or (at your option) any later version.
       This program is distributed in the hope that it  will  be  useful,  but
       WITHOUT  ANY  WARRANTY;  without  even  the  implied  warranty  of MER-
       CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the  GNU  General
       Public  License  for  more details.  You should have received a copy of
       the GNU General Public License along with this program; if  not,  write
       to  the  Free  Software  Foundation,  Inc., 59 Temple Place, Suite 330,
       Boston, MA 02111-1307 USA.

BUGS
       There probably are some, but we don't know what they are yet.

AUTHORS
       Neil Matthew and Rick Stones

                                                                      MYAPP(1)

Referensi
1. Beginning Linux Programming Books, John Wiley & Sons, 3rd Edition, 2004, p365-416

Iklan
Tag: , ,

2 Komentar to “Menulis Halaman Manual di Linux”

  1. ok coy…lumayan bisa dapet elmu gartis…
    oh ya…kalau convert dari textfile ke format Groff gimana ya…??

  2. makasih ilmunya mas, saya sudah terbantu dengan tutorial ini, makasih ya mas !!

Tinggalkan Balasan

Isikan data di bawah atau klik salah satu ikon untuk log in:

Logo WordPress.com

You are commenting using your WordPress.com account. Logout / Ubah )

Gambar Twitter

You are commenting using your Twitter account. Logout / Ubah )

Foto Facebook

You are commenting using your Facebook account. Logout / Ubah )

Foto Google+

You are commenting using your Google+ account. Logout / Ubah )

Connecting to %s

%d blogger menyukai ini: