Projet mkd/mkd/Help

De Wiki EELL.

Version du 4 mars 2013 à 16:25

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

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

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')

In follwed example H and D are used to decode the documentation.
Usage :

• D or F Fonctions - to generate the functions documentation
• G General - general documentation
• H Header - to generate the header file.h
• M Manual (In english. Under Unix / Linux : « Man (1) » or others )
• O Organigram or pseudo-code
• P Programmers - programmers doc (V cycle)
• S Structur - {/*S*/ ... or with "//" }//S
• U Users - doc. for final users
• e note in english
• f note in french
• w warnings - Attention !

All ASCII characters are utilisables, lettres et chiffres.

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