Projet mkd/mkd/Help
De Wiki EELL.
(Différences entre les versions)
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
