User:Goelette.Cardabela/sandbox/Mkd (Unix command)
This is my working page for Mkd --Goelette.Cardabela (talk) 17:37, 23 February 2013 (UTC)
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
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
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
/*D fonction cpp_ ----------------------------------------------------------------------------- ACTION: La fonction cpp_ lit le fichier source (pnfile) qui est transmis en paramètre et décode les lignes de commentaires précodés dans le style C++ puis les transcrit dans le fichier de destination (pfdoc) lorsque le code correspond à un des codes externes à la fonction; Les variables globales sont les codes et les options. Les codes, tabeau de 5 caractères: extern char codes[]; ils doivent être définis dans le programme d'appel: char codes[5] = {0,0,0,0,0}; Les options, n,s,t,v. extern unsigned char n,s,t,v; elles doivent définies dans le programme d'appel: unsigned char n=0,s=0,t=0,v=0; Avec les options : n: La transcription est précédée du numéro de ligne. Ceci permet d'atteindre facilement la ligne commentée. t: Avec l'option t seul le texte commenté est recopié. Sans l'option t le commentaire est entièrement recopié. Cette option t permet donc de générer des documents directement exploitables ou publiables. s: ajoute le commentaire à l'écran. v: mode bavard Remarque : Si la dédection d'un commentare à transcrire commence par le caractère '/' suivi de '*' il sera transcrit jusqu'à rencontrer le caractère '*' suivi de '/', quel que soit le commentaire ligne inclus dans ce commentaire. Si la détection d'un commentaire commence par deux caractères '/', le commentaire sera copié jusqu'au prochain retour à la ligne (NL) ou fin de fichier (EOF). Ces dispositions facilitent la génération automatique des fichiers d'entête fichier.h ou .hpp etc. SYNTAXE: #include "version.h" #include "cpp_.h" int cpp_(FILE *pfdoc, FILE *pnfile); PORTABILITE: Microsoft Visual studio sous Windows : x86(Win32) x64(Win32 et WIN64) gcc sous Linux. DESCRIPTION: cpp_ fonction FILE* pfdoc: pointeur sur le fichier de destination ouvert par le programme appelant. FILE* pnfile: pointeur sur le fichier source ouvert par le programme appelant VALEUR RETOURNEE: Retourne 0 en cas de succès. DROIT DE COPIE: (précisé dans version.h) : */ /*H // cpp_.c: extern int cpp_ (FILE *pfdoc, FILE *pnfile); */
All the paths to the files of the application are groupped in a project file in the call 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.
Manuals
Updated manuals
Update all translated manuals (See External links)
English UNIX manual
MKD(1) NAME mkd - make documentation. Extract coded informations from programs sources and product specific documentation. SYNOPSIS mkd [-ABCFPSafjlpstw] char_codes path_source [path_target] DESCRIPTION mkd Selected comments (or all comments) are extracted from programs sources and product specific documentation to target file. Usual target files are Organization charts, or Structure of programs, or comments for Programmers, Warnings and T ests points .... Coded informations are respectively 'O', 'S', 'P', 'www', and 'T' just after the comment character. char_codes All ASCII. The comment are extracted if the comment begin with this character. With two star mkd extract all comments. path_source Path source file (or project file: option j ). path_target Path target file. Default, path target is identical to source file with extension ´.doc´ . OPTIONS Upper case options: restrict comments to one specific language: -A extract Assembler style comments ( ; to end of line ) -B Basic style (REM or ' -> end of line) -C C style ( / * -> * / ) -F Fortran style (c,C or * -> end of line) -P Pascal style ( { -> } ) -S Shell or ratfor style ( # -> end of line) Lower case options: -a append to current target file. -f find source file language. (useful with project file) -j used if source file is a project file. -l lines (extract lines delimited by CD1 or CD2 in first column or CD3 in line, and next New-Line. CD1, CD2, CD3 are compilable options in version.h from mkd distribution) -p page (extract text delimited by CD4 and CD5 -begin with CD4 and end with CD5-. CD4, CD5 are compilable options in version.h from mkd distribution) -s add to screen. (verbose) -t text (copy only the comment). -w overwrite the current target file. EXAMPLES with C shell command: mkd -Ct F manual mkd.1 | gzip -f mkd.1.gz Product UNIX manual for French users. mkd -Ct M manual mkd.1 | gzip -f mkd.1.gz Product UNIX manual. mkd -Csl '*Sied' mkd3.c '*.verif_struct' Product documentation with structure of program, includes, defines, ifdef else and endif compile options, to verify struc‐ ture of program. (with compilable options CD1='#' or CD2='#' in version.h from mkd distribution). mkd -jfsl '*OHie' mkd_docu.prj mkd.org Product organization chart. Comment begin with '*','O','H', and sources files are itemized in project file. Options: 'f' find languages, 'j' specifies that the source file is a project file. (with compilable options CD1='#'or CD2='#'). mkd -l '*ide' mkd3.c '*.id_ei' (with compilable options CD1='#' or CD2='#'). mkd -pj '**' mkd_docu.prj mkd.strings Extract strings from program. (messages are printed to stdout). (sources files are itemized in project file, and with compilable options CD4=CD5=´\"´). mkd (without argument) Cause any error and syntax are transmitted to terminal. SEE ALSO mkdcppw(1) HISTORY 1986 - mkd for DOS, and mkdoc for UNIX, are written in ASCII format by Jean-Paul Louyot for the 'CEM' of the University of Montpelier labo- ratory (France). 1991 - mkdoc 3.12 for PC and UNIX (Sun) 1995 - mkdoc 3.22 for Linux Red-Hat 2004 - mkdoc 4 for SUN-SPARC, HP-UX, RedHat, Windows 98, Windows 2000 2007-2012 - mkdoc release 7.01 to mkd R12.01 are in format ISO-8859-1. The name 'mkdoc' is abandoned with the release 10.01 compiled with Visual C++ 2010 2012 - mkd 12.03 is adapted to UTF-8 format for translations and internationalization. In the wake mkdcppw is written to decode computer C, c++ and php languages in graphical mode with 'gcc' and 'gtkmm'. AUTHORS Updated by : Clara JIMENEZ. Translations : Alizée (Catalan, Spanish), Luca (Italian). http://edeulo.free.fr/wiki/index.php/Projet_mkd/Compilations_UNIX-LINUX NOTES No match to read and decode the files included in the sources files in this Release 12.05.0 BUGS Bugs Report: http://edeulo.free.fr/phpBB3/index.php Documents generator mkd 3 December 2012 MKD(1)
Operating systems
Debian and Ubuntu
mkd is provided and distributed as ubuntu packages.[3]
See chapter External links
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.
See also
Comparison of documentation generators
External links
- ISO/IEC 26514:2008 preview
- mkd project Présentation of the mkd project and its derivatives on the site of the maintainers.
- Downloads for debian systems and ubuntu software library and updated translated manuals.
Downloads sources : Sources for other systems (UNIX, LINUX, WINDOWS)
References
- ^ ISO/IEC 26514:2008
- ^ (1986-2001) Service 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