User:Goelette.Cardabela/sandbox/Mkd (Unix command)

From Wikipedia, the free encyclopedia
Jump to: navigation, search

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

/*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.

 SYNTAXE:
        #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);
*/

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]

Update all translated manuals (See External links)

English UNIX manual[edit]

Operating systems[edit]

Debian and Ubuntu[edit]

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

See chapter External links

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.

See also[edit]

Comparison of documentation generators

External links[edit]

Downloads sources : Sources for other systems (UNIX, LINUX, WINDOWS)

References[edit]

  1. ^ ISO/IEC 26514:2008
  2. ^ (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
  3. ^ ubuntu packages