Projet mkd/mkd/Help

De Wiki EELL.

(Différences entre les versions)
m (Command file and Makefile : Ajout d'une section sur l'utilisation de mkddocu)
m (Make documentation with mkddocu : Correction de lien)
Ligne 141 : Ligne 141 :
You can copy the shell '''/usr/bin/mkddocu''' in the sources directory and rename this file (mkddoc.sh). Shell that can be adapted at will.  
You can copy the shell '''/usr/bin/mkddocu''' in the sources directory and rename this file (mkddoc.sh). Shell that can be adapted at will.  
-
See the [[Shell_command_projects/mkd#Manuel_mkddocu_en_fran.C3.A7ais|manuel de mkddocu]]<br>
+
See the [[Shell_command_projects/mkd#Manual_mkd_in_english|manuel de mkddocu]]<br>
SQee also the discussion [http://edeulo.free.fr/phpBB3/viewtopic.php?f=16&t=323&p=382#p382 mkd 140515 disponible]
SQee also the discussion [http://edeulo.free.fr/phpBB3/viewtopic.php?f=16&t=323&p=382#p382 mkd 140515 disponible]
[[Catégorie:Documentation]]
[[Catégorie:Documentation]]
[[Catégorie:Mkd]]
[[Catégorie:Mkd]]

Version du 13 décembre 2014 à 15:40

Return to Shell_command_projects/mkd

Sommaire

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

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

  • D or F Functions - 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 pseudocode
  • P Programmers - programmers doc (V cycle)
  • S Structure - {/*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 used, letters and number.

 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 warning doc. for programmers
     else \
          @echo "The mkd command is not found in the /usr/bin directory"; \
     fi

Make documentation with mkddocu

mkddocu is a utility introcuced with mkd may 2014. (mkd-doc_140515_all.deb)

This utility facilitates the standard edition of the software documentation.

Place the command mkddocu in the compilation file or in the Makefile.

You can copy the shell /usr/bin/mkddocu in the sources directory and rename this file (mkddoc.sh). Shell that can be adapted at will.

See the manuel de mkddocu
SQee also the discussion mkd 140515 disponible

Outils personnels