Jump to content

User:Goelette Cardabela/sandbox/mkd (Unix command)

From Wikipedia, the free encyclopedia

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

[edit]

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

[edit]

Functions files

[edit]

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 und 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

[edit]

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

[edit]

Updated manuals

[edit]

See External links

English UNIX manual

[edit]
MKD(1) Manual (3 December 2012)
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

[edit]

Debian and Ubuntu

[edit]

mkd is provided and distributed as ubuntu packages.[3]

Fedora and Red Hat

[edit]

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

[edit]

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

[edit]

mkd for MS-Windows is used in command line on a terminal emulator cmd.

See External links

See also

[edit]

Comparison of documentation generators

[edit]

References

[edit]
  1. ^ ISO/IEC 26514:2008
  2. ^ (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
  3. ^ ubuntu packages
Retrieved from "https://en.wikipedia.org/w/index.php?title=User:Goelette_Cardabela/sandbox/mkd_(Unix_command)&oldid=542782855"