Mkd (Unix command)
De Wiki EELL.
 | Call for translation and help.
Veuillez considérer le plan et le contenu comme incomplets et en préparation, temporaires et sujets à caution. Si vous souhaitez participer, nous aider à traduire, il vous est recommandé de consulter sa page de discussion au préalable. |
mkd is a Unix command to extract pre-encoded comments lines to generate the software documentation according to ISO[1] standards. mkd is the abbreviation of make documentation. This command was originally known under the name mkdoc (make documentation).[2]
This command is not integrated into the standard distributions of Unix / Linux
Sommaire |
Command line syntax
The following command in a terminal emulator or in a konsole :
- nadine@Nadine-computer-on-linux:~$ mkd \?
display the syntax :
mkd UNIX version, Release 12.03, USAGE:
syntax: mkd [-ABCFPSafjlnpstvw] char_codes path_source [path_target]
or: mkd \? .See also nanual: 'man mkd'
--> options:
-A decode Assembler comment style only
-B Basic style
-C C++ style
-F Fortran style
-P Pascal style
-S Shell style
-a append target file
-f:
find language ( .s .S .c .h .i .f .F .r .p .sh .csh )
-j use only with project sources file.
-l and p; line: (compil.: % or - in first column or # in line)
page: (compil.: begin with " and end with ")
-n insert line number
-s copy and add to screen
-t copy the comment only
-v verbose
-w overwrite (default option: switch off)
--> char_codes: all ASCII (5 char max)
example codes = UM or \*OPTw or '* HOS' or '**' for all
--> path_source: source file (option j: if it is a project file)
--> path_target: target file
Example: mkd -Csnv '*S' file.c \*.verif_structure
.Exit 2
Example of use
Functions files
When possible, they wrote each function in a separate computer file.
When the functions are grouped in a single file, the documentation will appear in the same order as in the file.
In function file must specifify usage, and syntax for header file.
Example for cpp_ function : in cpp_.c file
/*P
File cpp_.c
Programmers directives (in V cycle)
Last Date and Programmer name
*/
/*D
function cpp_
-----------------------------------------------------------------------------
ACTION:
The cpp_ function reads the source file (pnfile) transmitted from the
calling function, and décodes the comments pre-encoded in lines or
blocks of style c++. and then writing this comments in a target file
(pfdoc).
Pre-coded characters are defined in a external global table 'Codes';
The golbal variables are 'Codes' and 'Options'.
The 'Codes': table of 5 characters:
extern char codes[];
They must be défined in the calling function:
char codes[5] = {0,0,0,0,0};
The 'Options': n,s,t,v.
extern unsigned char n,s,t,v;
They must be défined in the calling function:
unsigned char n=0,s=0,t=0,v=0;
With the options:
n: The transcript is preceded by line number. This allows to easily
reach the commented line.
t: With the t option only the commented text is copied.
Without the t option the entire line or block is copied.
The-t option permit to generate directly exploitable and
publishable documents.
s: Add le comment to the screen to use shell redirections > , >> ,
or || etc.
v: Verbose mode.
Remark:
If the decoded comment begins with the characters "/*", the comment
is copied until find the characters "*/", whatever included any
comment-line starting with "//".
If the decoded comment begins with the characters "//", the line is
copied until find the end-of-line or new-line 'NL' character or
end-of-file 'EOF'.
This provisions facilitate the automatic generation of header files
(file.h ; .hpp ; etc.) and documentation of functions.
SYNTAX:
#include "version.h"
#include "cpp_.h"
int cpp_(FILE *pfdoc, FILE *pnfile);
PORTABILITY:
Microsoft Visual studio under Windows : x86(Win32) x64(Win32 and WIN64)
gcc under Unix/Linux.
DESCRIPTION:
cpp_ fonction
FILE * pfdoc: pointer of the target file opened by the calling function.
FILE * pnfile: pointer of the source file opened by the calling function
RETURN VALUE:
Return 0 in case of success.
COPYRIGHT: (Specified in version.h) :
*/
/*H
// cpp_.c:
extern int cpp_ (FILE * pfdoc, FILE * pnfile);
*/
int cpp_ (FILE * pfdoc, FILE * pnfile)
{ //S Function Begin
... // Function Lines
} //S Function End
Command file and Makefile
All the paths to the files of the application are writen in a project file in the alphabetical order.
- Example : "ls -1 *.c > app.prj" will contain the name of all files to generates the sofware documentation. Attention, ls -1 (number) and not -l (character 'l')
The command line : "mkd -Cjt H app.prj app.h" generates the header file off all functions of the application.
The command line : "mkd -Cjt D app.prj app_functions.documentation" generates the documentation of all functions of the application.
Example of lines included in a Makefile
In this example the Makefile is in the sources files.
APP = MyProgram # This is any "macro"
Create_header_and_functions-doc: # here, this is any unconditional directive.
if [ -e "/usr/bin/mkd" ]; \ # Warning: the first char is a tabulation and not spaces
then \
ls -1 *.cpp > $(APP).prj; \ # first create or overwrite new project file
mkd -Ctw H $(APP).prj $(APP).h: \ # create or overwrite header file
mkd -Ctw D $(APP).prj $(APP).txt: \ # create or overwrite functions documentation
mkd -Cwn w $(APP).prj $(APP).wars; \# create or overwrite warnind documentation for programmers
else \
@echo "The mkd command is not installed in bin directory"; \
fi
Manuals
Updated manuals
See External links
English UNIX manual
Operating systems
Debian and Ubuntu
mkd is provided and distributed as ubuntu packages.[3]
Fedora and Red Hat
Tue application heas been intensely used with Red-Hat on PC, on SUN Sparc and HP-UX, up of the year 2000 in the ASCII format ; The location of the directories was different from the current location (man, whatis, ...)
mkd is compilable 'as is' for Fedora. (Format of characters UTF-8)
The RPM packets are not distributed by the maintainers.
Other LINUX distribution
Many Linux distribution are available. mkd is, in principle, compatible with all Unix and Linux systems, except, sometimes, the location of the manuals and documentations directories.
DOS/Windows
mkd for MS-Windows is used in command line on a terminal emulator cmd.
See External links
See also
Comparison of documentation generators
External links
- ISO/IEC 26514:2008 preview
- Downloads for debian systems, ubuntu software library, and updated translated manuals.
- Downloads sources for other systems (Unix, Linux, Windows)
References
- ↑ ISO/IEC 26514:2008
- ↑ (1986-2001) Informatique - Centre d'Electronique et de Micro-électronique de Montpellier, Université Montpellier II, 34000 Montpellier France
www.cem2.univ-montp2.fr. See new laboratory IES - ↑ ubuntu packages
