diff options
| -rw-r--r-- | newlib/HOWTO | 117 | ||||
| -rw-r--r-- | newlib/doc/doc.str | 17 | ||||
| -rw-r--r-- | newlib/doc/makedoc.c | 76 |
3 files changed, 163 insertions, 47 deletions
diff --git a/newlib/HOWTO b/newlib/HOWTO new file mode 100644 index 000000000..6a0f2a92f --- /dev/null +++ b/newlib/HOWTO @@ -0,0 +1,117 @@ +This HOWTO file contains notes for maintainers and contributors to Newlib. +For information on using Newlib (building, installing), see README. (In +particular, the "Regenerating Configuration Files" section in README is of +interest to both users and contributors.) + +(This file could probably use some other "sections" in addition to the +initially-provided sections. Please help by adding as appropriate.) + +DOCUMENTATION +============= + + All the documentation for Newlib comes as part of the machine-readable +distribution. Functions are documented in the source files, although not +every file contains documentation, as many functions share manual page +information. For example, lround(), lroundf(), llround(), and llroundf() +share a single man page, which is in the source for lround(). The documentation +is written partially in a custom format and partially in Texinfo format. + + The custom part comprises makedoc.c and doc.str, both of which are in the +doc directory. doc.str is a macro file that can be used to define things to +be done by makedoc, using building blocks that are built into makedoc.c. +The basic function of makedoc is two-fold. First, it recognizes comments in +the proper format to pull out of source files. Second, it adds some Texinfo +commands as well as translating certain sequences into the appropriate +Texinfo commands. Refer to makedoc.c and doc.str for what these are. +(makedoc.c is not particularly-well commented.) Another way to see how they +work is to simply examine the source files with documentation comments. + +(A couple of examples that use some of the fancier options: + libm/common/s_isnan.c ("o+" variable-"bullet" list), + libc/stdio/sprintf.c ("O+" bullet list; "." for example code).) + + In addition to the makedoc.c stuff, Texinfo commands can be directly +used. Texinfo is a documentation system that uses a single source file to +produce both on-line information and a printed manual. You can use one of the +Info formatting commands to create the on-line version of the documentation +and TeX (or `texi2roff') to typeset the printed version. While Newlib contains +a copy of the texinfo package (texinfo.tex), the manual for it is not +included. The latest one may be found at + +http://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html + +(which could be for a newer version of texinfo.tex than is included in Newlib). + + In addition to Texinfo commands, straight TeX commands can also be used, +but these, however, should be carefully limited and be given alternates for +when a non-printed manual is produced--such as when info pages are produced. +For an example of this kind of usage, see libm/common/s_logb.c. + + Please note that most files with documentation contain both an +ANSI_SYNOPSIS and a TRAD_SYNOPSIS section. The TRAD_SYNOPSIS section gets +deleted (since at least 2000) by makedoc, so when working on files these +can safely be deleted and if you're making a new file, there is no need +to add the TRAD_SYNOPSIS section. + + If writing a new function that requires documentation, the required +sections are FUNCTION, INDEX, ANSI_SYNOPSIS (or SYNOPSIS), DESCRIPTION, RETURNS, +and PORTABILITY. BUGS and SEEALSO should be added as appropriate. + + Source files which contain documentation are processed into ".def" +files with the extracted information. These .def files are noted in the +makefiles as either CHEWOUT_FILES in the libc makefiles or chobj in the libm +makefiles. These .def files need to be included into an appropriate .tex +file for inclusion in the manuals (one each for libc and libm). Pay special +attention under libc, as the manual is arranged by header file name, but not +all header files are represented by directories (e.g. wcsftime.c is found +under libc/time, but goes under wchar.h in the manual.) + +In summary, to add new documentation: + +1. Add properly-formatted comments to source file (e.g. src.c); +2. add "chewout" file to list in Makefile.am (CHEWOUT_FILES in libc or chobj in + libm) (e.g. src.def), re-generate Makefile.in; +3. add file to something.tex; +4. make ChangeLog entry and generate patch. + +EL/IX (ELIX_LEVEL_n, ELIX_n_SOURCES) +==================================== + + Some of the Makefiles contain definitions of ELIX_LEVEL_1 ... ELIX_LEVEL_4, +and corresponding definitions for ELIX_1_SOURCES ... ELIX_4_SOURCES. +These are referring to the EL/IX standards created by Red Hat for the +purpose of Linux-based open standards for embedded development. In brief, +the intent is to define multiple levels for API functions that allows the +user to size the library appropriately for their application--at least in +terms of the predefined lists. For full details, refer to the EL/IX home +page at http://sources.redhat.com/elix/. The likely best way to tell how to +classify any new functions in terms of needing an ELIX level qualification +is to ask Jeff Johnston. To see how it works and try classification on your +own, refer to the API specification on the web site, + +http://sources.redhat.com/elix/api/current/api.pdf. + +(Unfortunately, it is not complete with respect to either the C99 or POSIX +standards, so particular C and POSIX functions may or may not be found.) + + The following definitions of the levels are from the (draft) standard. + +Level 1 + RTOS compatible layer. Functions available in both Linux and a +typical deeply embedded operating system (eCos, RTEMS, VxWorks, pSOS, VRTX32, +etc.). Some functions may have reduced or modified semantics. + +Level 2 + Linux single process only. Includes level 1 plus any functions from Linux +that are not easily implemented on an RTOS. Also full implementations of +reduced functions in Level 1. + +Level 3 + Linux multiprocess for embedded applications. This is basically POSIX.1 +with some of the functions that are obviously not for embedded applications +(such as job control) removed. + +Level 4 + Full POSIX or Linux compliance. Essentially these are functions that are +present in a standard Linux kernel but are irrelevant to an embedded system. +These functions do not form part of the EL/IX API. diff --git a/newlib/doc/doc.str b/newlib/doc/doc.str index 4d557c6f5..51ecef7f4 100644 --- a/newlib/doc/doc.str +++ b/newlib/doc/doc.str @@ -22,10 +22,6 @@ quickref ; - -: ITEM - "@item " catstr ; - : EXAMPLE skip_past_newline @@ -55,7 +51,6 @@ ; - : ANSI_SYNOPSIS skip_past_newline "@strong{Synopsis}\n" catstr @@ -137,8 +132,6 @@ bodytext ; - - : DESCRIPTION "@strong{Description}@*\n" catstr subhead ; @@ -148,31 +141,29 @@ : ERRORS "@strong{Errors}@*\n" catstr subhead ; - : PORTABILITY "@strong{Portability}@*\n" catstr subhead ; +: BUGS + "@strong{Bugs}@*\n" catstr subhead ; : WARNINGS "@strong{Warnings}@*\n" catstr subhead ; - +: SEEALSO + "@strong{See Also}@*\n" catstr subhead ; : INTERNAL_FUNCTION func ; - : INTERNAL_DEFINITION func ; - : INTERNAL func ; : TYPEDEF FUNCTION ; - - : NEWPAGE "@page\n" catstr subhead ; diff --git a/newlib/doc/makedoc.c b/newlib/doc/makedoc.c index 00ff75c42..0bbffb66b 100644 --- a/newlib/doc/makedoc.c +++ b/newlib/doc/makedoc.c @@ -39,12 +39,15 @@ There is no #include <stdio.h> #include <stdlib.h> #include <ctype.h> +#include <string.h> #define DEF_SIZE 5000 #define STACK 50 +#define MIN_CMDLEN 4 /* Minimum length of a command */ int internal_wanted; int internal_mode; +int Verbose=0; @@ -212,7 +215,7 @@ string_type *tos; unsigned int idx = 0; /* Pos in input buffer */ string_type *ptr; /* and the buffer */ -typedef void (*stinst_type)(); +typedef void (*stinst_type)(NOARGS); stinst_type *pc; stinst_type sstack[STACK]; stinst_type *ssp = &sstack[0]; @@ -234,7 +237,7 @@ struct dict_struct }; typedef struct dict_struct dict_type; -#define WORD(x) static void x() +#define WORD(x) static void x(NOARGS) static void DEFUN(exec,(word), dict_type *word) @@ -451,7 +454,6 @@ WORD(translatecomments) WORD(quickref) { string_type *nos = tos-1; - unsigned int scan=0; unsigned int nosscan = 0; unsigned int idx = 0; @@ -487,6 +489,7 @@ WORD(quickref) } +#if 0 /* turn everything not starting with a . into a comment */ WORD(manglecomments) @@ -520,6 +523,7 @@ WORD(manglecomments) pc++; } +#endif /* Mod tos so that only lines with leading dots remain */ static void @@ -640,12 +644,15 @@ WORD(courierize) } /* +bulletize: look for bullet item commands at start of line + Bullet list: O+ emit @itemize @bullet - OO emit @item + o emit @item [note lowercase] O- emit @end itemize + Variable label list: o+ emit @table @code - oo @item + o emit @item o- emit @end table */ @@ -653,19 +660,10 @@ WORD(courierize) WORD(bulletize) { unsigned int idx = 0; - int on = 0; string_type out; init_string(&out); while (at(tos, idx)) { - if (at(tos, idx) == '@' && - at(tos, idx+1) == '*') - { - cattext(&out,"*"); - idx+=2; - } - - else if (at(tos, idx) == '\n' && at(tos, idx+1) == 'o') { if (at(tos,idx+2) == '+') { @@ -787,7 +785,10 @@ DEFUN( iscommand,(ptr, idx), } else if(at(ptr,idx) == '\n') { - if (len >4) return 1; + /* The length check will never fail on a real command + * because the commands are screened as the definitions file + * is read. */ + if (len >= MIN_CMDLEN) return 1; return 0; } else return 0; @@ -797,6 +798,7 @@ DEFUN( iscommand,(ptr, idx), } +unsigned int DEFUN(copy_past_newline,(ptr, idx, dst), string_type *ptr AND unsigned int idx AND @@ -833,7 +835,6 @@ WORD(kill_bogus_lines) { int sl ; - int nl = 0; int idx = 0; int c; int dot = 0 ; @@ -1162,9 +1163,6 @@ static void DEFUN_VOID(perform) /* It's worth looking through the command list */ if (iscommand(ptr, idx)) { - unsigned int i; - int found = 0; - char *next; dict_type *word ; @@ -1178,6 +1176,7 @@ static void DEFUN_VOID(perform) if (word) { + if(Verbose) fprintf(stderr, "CMD '%s'\n", word->word); exec(word); } else @@ -1234,19 +1233,13 @@ return entry->code_end++; void DEFUN(add_intrinsic,(name, func), char *name AND - void (*func)()) + void (*func)(NOARGS)) { dict_type *new = newentry(name); add_to_definition(new, func); add_to_definition(new, 0); } -WORD(push_addr) -{ - - -} - void DEFUN(add_var,(name), char *name) @@ -1261,13 +1254,12 @@ DEFUN(add_var,(name), -void +int DEFUN(compile, (string), char *string) { - int jstack[STACK]; - int *jptr = jstack; + int ret=0; /* add words to the dictionary */ char *word; string = nextword(string, &word); @@ -1275,18 +1267,24 @@ DEFUN(compile, (string), { if (strcmp(word,"var")==0) { - string=nextword(string, &word); + string=nextword(string, &word); add_var(word); - string=nextword(string, &word); + string=nextword(string, &word); } -else + else if (word[0] == ':') { dict_type *ptr; /* Compile a word and add to dictionary */ string = nextword(string, &word); + if(Verbose) fprintf(stderr, "Found command '%s'\n", word); + if(strlen(word) < MIN_CMDLEN) { + fprintf(stderr, "ERROR: Command '%s' is too short ", word); + fprintf(stderr, "(MIN_CMDLEN is %d)\n", MIN_CMDLEN); + ret++; + } ptr = newentry(word); string = nextword(string, &word); @@ -1330,9 +1328,11 @@ else else { fprintf(stderr,"syntax error at %s\n",string-1); + ret++; } } +return(ret); } @@ -1378,11 +1378,13 @@ static void DEFUN(read_in, (str, file), } +#if 0 static void DEFUN_VOID(usage) { - fprintf(stderr,"usage: -[d|i|g] <file >file\n"); + fprintf(stderr,"usage: -[i|v] -f macrofile <file >file\n"); exit(33); } +#endif int DEFUN(main,(ac,av), int ac AND @@ -1446,16 +1448,22 @@ char *av[]) fprintf(stderr,"Can't open the input file %s\n",av[i+1]); return 33; } + if(Verbose) fprintf(stderr, "Reading -f '%s'\n", av[i+1]); read_in(&b, f); - compile(b.ptr); + if( compile(b.ptr) ) { fclose(f); exit(1); } perform(); + fclose(f); } else if (av[i][1] == 'i') { internal_wanted = 1; } + else if (av[i][1] == 'v') + { + Verbose++; + } } } |