Voir le texte source

[[Shell_command_projects/mkd|<span style = "color:Blue";><small>Return to Shell_command_projects/mkd</small></span>]] ↑

== Example of use ==
=== Functions files ===
When possible, they wrote each function in a separate [[:wikipedia:Computer file|'''computer file''']].<br />
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 [[:wikipedia:Header file|'''header file''']].

Example for cpp_ function : in cpp_.c file
<pre style="color:red">
/*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);
*/
</pre>
<pre style="color:blue">
     int cpp_ (FILE * pfdoc, FILE * pnfile)
     { //S Function Begin
       ... // Function Lines
     } //S Function End
</pre>

=== 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.
<br />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.
<pre style="color:black;background-color:#FFC;">
 The command line : "'''mkd -Cjt H app.prj app.h'''"
 generates the header file off all functions of the application.
</pre>
<pre style="color:black;background-color:#FFC;">
 The command line : "'''mkd -Cjt D app.prj app_functions.documentation'''"
 generates the documentation of all functions of the application.
</pre>
Example of lines included in a Makefile<br />
In this example the Makefile is in the sources files.
<pre style="color:blue">
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
</pre>

== 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 [[Shell_command_projects/mkd#Manual_mkddocu_in_english|manual of mkddocu]]<br>
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:Mkd]]