doc: add more details about adding documentation to HOWTO

Message ID 20191219145011.2327-1-jon.turney@dronecode.org.uk
State Accepted
Commit 7685c4dd6c77a4177dfbbf91ac255053171cc41f
Headers show
Series
  • doc: add more details about adding documentation to HOWTO
Related show

Commit Message

Jon Turney Dec. 19, 2019, 2:50 p.m.
Add a little more detail to the checklist for adding documentation
Also update the list of supported sections
---

Notes:
    This extends the checklist for adding documentation, to include the
    details mentioned in [1] et seq.
    
    [1] https://sourceware.org/ml/newlib/2019/msg00464.html

 newlib/HOWTO | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

-- 
2.21.0

Comments

Corinna Vinschen Dec. 19, 2019, 5:17 p.m. | #1
On Dec 19 14:50, Jon Turney wrote:
> Add a little more detail to the checklist for adding documentation

> Also update the list of supported sections

> ---

> 

> Notes:

>     This extends the checklist for adding documentation, to include the

>     details mentioned in [1] et seq.

>     

>     [1] https://sourceware.org/ml/newlib/2019/msg00464.html

> 

>  newlib/HOWTO | 6 ++++--

>  1 file changed, 4 insertions(+), 2 deletions(-)

> 

> diff --git a/newlib/HOWTO b/newlib/HOWTO

> index bb49e79dd..3a214edf4 100644

> --- a/newlib/HOWTO

> +++ b/newlib/HOWTO

> @@ -49,7 +49,8 @@ For an example of this kind of usage, see libm/common/s_logb.c.

>  

>       If writing a new function that requires documentation, the required

>  sections are FUNCTION, INDEX, SYNOPSIS, DESCRIPTION, RETURNS,

> -and PORTABILITY.  BUGS and SEEALSO should be added as appropriate.

> +and PORTABILITY.  BUGS, NOTES, SEEALSO and WARNINGS 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

> @@ -64,7 +65,8 @@ In summary, to add new documentation:

>  1.  Add properly-formatted comments to source file (e.g. src.c);

>  2.  add "chewout" file to CHEWOUT_FILES list in Makefile.am (e.g. src.def),

>      re-generate Makefile.in;

> -3.  add file to something.tex;

> +3.  @include that .def file in the appropriate .tex file, add texinfo menu

> +    entries that reference the @node(s) in that .def file;

>  4.  make ChangeLog entry and generate patch.

>   

>  EL/IX (ELIX_LEVEL_n, ELIX_n_SOURCES)

> -- 

> 2.21.0


Looks good, please push.


Thanks,
Corinna

-- 
Corinna Vinschen
Cygwin Maintainer
Red Hat

Patch

diff --git a/newlib/HOWTO b/newlib/HOWTO
index bb49e79dd..3a214edf4 100644
--- a/newlib/HOWTO
+++ b/newlib/HOWTO
@@ -49,7 +49,8 @@  For an example of this kind of usage, see libm/common/s_logb.c.
 
      If writing a new function that requires documentation, the required
 sections are FUNCTION, INDEX, SYNOPSIS, DESCRIPTION, RETURNS,
-and PORTABILITY.  BUGS and SEEALSO should be added as appropriate.
+and PORTABILITY.  BUGS, NOTES, SEEALSO and WARNINGS 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
@@ -64,7 +65,8 @@  In summary, to add new documentation:
 1.  Add properly-formatted comments to source file (e.g. src.c);
 2.  add "chewout" file to CHEWOUT_FILES list in Makefile.am (e.g. src.def),
     re-generate Makefile.in;
-3.  add file to something.tex;
+3.  @include that .def file in the appropriate .tex file, add texinfo menu
+    entries that reference the @node(s) in that .def file;
 4.  make ChangeLog entry and generate patch.
  
 EL/IX (ELIX_LEVEL_n, ELIX_n_SOURCES)