Projet mkd/mkd/Help
De Wiki EELL.
m (Catégorisation) |
m (→Command file and Makefile : Ajout d'une section sur l'utilisation de mkddocu) |
||
Ligne 130 : | Ligne 130 : | ||
fi | fi | ||
</pre> | </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#Manuel_mkddocu_en_fran.C3.A7ais|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] | ||
[[Catégorie:Documentation]] | [[Catégorie:Documentation]] | ||
[[Catégorie:Mkd]] | [[Catégorie:Mkd]] |
Version du 13 décembre 2014 à 15:35
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