[patch, libgomp, docs] adding documentation to libgomp

[patch, libgomp, docs] adding documentation to libgomp

[Daniel Franke]

[-- Attachment #1: Type: text/plain, Size: 2126 bytes --]


:ADDPATCH libgomp:

This manual documents the usage of libgomp, the GNU implementation of
the OpenMP (http://www.openmp.org) Application Programming Interface
(API) for multi-platform shared-memory parallel programming in C/C++
and Fortran.

* Menu:

* Enabling OpenMP::            How to enable OpenMP for your Applications.
* Runtime Library Routines::   The OpenMP Runtime Application Programming
                               Interface.
* Environment Variables::      Influencing runtime behavior with environment
                               variables.
* The libgomp ABI::            Notes on the external ABI presented by libgomp.
* Reporting Bugs::             How to report bugs in GNU OpenMP.
* Copying::                    GNU General Public License says
                               how you can copy and share GNU Fortran.
* GNU Free Documentation License::
                               How you can copy and share this manual.
* Funding::                    How to help assure continued work for free
                               software.
* Index::                      Index of this documentation.


Section 2 briefly documents the library routines as described by the OpenMP 
standard, section 3 describes standard and non-standard environment 
variables. The latter also implements PR28209. The contents of the file NOTES 
is included in section 4, "The libgomp ABI".

To allow libgomp.info to be distributed, the enable-generated-files-in-srcdir 
option was added to configure. Newly available targets are: info, dvi, pdf 
and html.

Tested on i686-pc-linux-gnu.

When reviewing this documentation, please keep in mind that I am not a native 
speaker: strange wording, typographical or grammatical errors are likely.

Thanks
	Daniel



2006-11-24  Daniel Franke  <franke.daniel@gmail.com>

	PR libgomp/28209
	* libgomp.texi: New file.
	* configure.ac: Add --enable-generated-files-in-srcdir option.
	* Makefile.am Add info, dvi, pdf, html targets. On request, copy files to 
srcdir.
	* Makefile.in: Regenerated.
	* config.h.in: Regenerated.
	* testsuite/Makefile.in: Regenerated.
	* NOTES: Removed.


[-- Attachment #2: libgomp.info.patch.gz --]
[-- Type: application/x-gzip, Size: 9339 bytes --]

Re: [patch, libgomp, docs] adding documentation to libgomp

[Diego Novillo]

Daniel Franke wrote on 11/23/06 18:09:

> 2006-11-24  Daniel Franke  <franke.daniel@gmail.com>
> 
> 	PR libgomp/28209
> 	* libgomp.texi: New file.
> 	* configure.ac: Add --enable-generated-files-in-srcdir option.
> 	* Makefile.am Add info, dvi, pdf, html targets. On request, copy files to 
> srcdir.
> 	* Makefile.in: Regenerated.
> 	* config.h.in: Regenerated.
> 	* testsuite/Makefile.in: Regenerated.
> 	* NOTES: Removed.
> 
First, thank you very much for documenting this.  I believe there is
some bugzilla PR that you are fixing with this patch.  Second, do you
have an FSF copyright assignment?

I can't approve the configury bits.  The documentation looks OK with
some changes below.  You'll need to have a doc maintainer go over the
texinfo formatting.

> Index: configure.ac
> ===================================================================
> --- configure.ac	(revision 119061)
> +++ configure.ac	(working copy)
> @@ -21,6 +21,20 @@
>    permit yes|no|default)
>  AC_MSG_RESULT($enable_linux_futex)
>  
> +# We would like to our source tree to be readonly. However when releases or
>
s/to our/our/

> +@menu
> +* omp_get_dynamic::          Whether Dynamic Teams Are Enabled
> +* omp_get_max_threads::      Maximum Number Of Threads
> +* omp_get_nested::           Whether Nested Parallel Regions Are Enabled
> +* omp_get_num_procs::        Number Of Processors Online
> +* omp_get_num_threads::      Size Of The Active Team
> +* omp_get_thread_num::       Current Thread ID
> +* omp_in_parallel::          Whether A Parallel Region is Active
> +* omp_set_dynamic::          Enable/Disable Dynamic Teams
> +* omp_set_nested::           Enable/Disable Nested Parallel Regions
> +* omp_set_num_threads::      Set Upper Team Size Limit
> +@end menu
> +
Does the right column need to be capitalized like that?  It looks
pretty bad.  Likewise in other menus.

> +@node omp_get_dynamic
> +@section @code{omp_get_dynamic} -- Whether Dynamic Teams Are Enabled
>                                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                                      Dynamic teams setting

> +@table @asis
> +@item @emph{Description}:
> +Whether the dynamic adjustment of the number of threads within a 
> +team is enabled or not.
>
Remove this.

> The function returns @code{true} if enabled, 
>
s/The/This/
> +@code{false} otherwise. Here, @code{true} and @code{false} represent 
> +their language-specific counterparts.

> +@node omp_get_max_threads
> +@section @code{omp_get_max_threads} -- Maximum Number Of Threads
> +@table @asis
> +@item @emph{Description}:
> +The maximum number of threads in a team if a parallel region
> +without a @code{num_threads} clause would be encountered.
> +
Return the maximum number of threads used for parallel regions that do
not use the clause @code{num_threads}.

> +@item @emph{C/C++}:
> +@multitable @columnfractions .20 .80
> +@item @emph{Prototype}: @tab @code{int omp_get_max_threads();}
> +@end multitable
> +
> +@item @emph{Fortran}:
> +@multitable @columnfractions .20 .80
> +@item @emph{Interface}: @tab @code{integer function omp_get_max_threads()}
> +@end multitable
> +
> +@item @emph{See also}:
> +@ref{omp_set_num_threads}, @ref{omp_set_dynamic}
> +
> +@item @emph{Reference}:
> +@uref{http://www.openmp.org/, OpenMP specifications v2.5}, section 3.2.3.
> +@end table
> +
> +
> +
> +@node omp_get_nested
> +@section @code{omp_get_nested} -- Whether Nested Parallel Regions Are Enabled
                                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
				     Nested parallel regions

> +@table @asis
> +@item @emph{Description}:
> +Whether nested parallel regions, i. e. team member spawning new teams, is 
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +enabled or not. The function returns @code{true} if enabled, @code{false} 
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +otherwise. Here, @code{true} and @code{false} represent their language-specific 
^^^^^^^^^^^^
> +counterparts.
> +
This function returns @code{true} if nested parallel regions are
enabled.  

> +@node omp_set_lock
> +@section @code{omp_set_lock} -- Wait For And Set Simple Lock
> +@table @asis
> +@item @emph{Description}:
> +Simple locks about to be set must not be uninitialized. The calling thread 
   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   I don't know what you are trying to say here.

> +@node omp_unset_lock
> +@section @code{omp_unset_lock} -- Unset Simple Lock
> +@table @asis
> +@item @emph{Description}:
> +Simple locks about to be unset must not be in a locked state and held by 
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Better move this to the end of the paragraph

> +the thread executing the routine. The lock becomes unlocked. If one ore more
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^  ^^^^^^^^^^^^^^^^^^^^^^^^^
                                     Non-sequitur.

> +threads attempted to set the lock before, one of them is chosen to, again, 
> +set the lock for itself.
> +
> +@node omp_test_nest_lock
> +@section @code{omp_test_nest_lock} -- Test And Set Nested Lock If Available
> +@table @asis
> +@item @emph{Description}:
> +Nested locks about to be set must not be uninitialized. Contrary to 
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This needs rephrasing.

> +@code{omp_set_nest_lock}, @code{omp_test_nest_lock} does not block if 
> +the lock is not available. If the lock is already hold by the current 
>
s/hold/held/

Re: [patch, libgomp, docs] adding documentation to libgomp

[Daniel Franke]

Diego,
thanks for reviewing. I will try to send in a revised patch by tomorrow.

2006/11/29, Diego Novillo <dnovillo@redhat.com>:
> > 2006-11-24  Daniel Franke  <franke.daniel@gmail.com>
> > 	PR libgomp/28209
> > 	* libgomp.texi: New file.
> > 	* configure.ac: Add --enable-generated-files-in-srcdir option.
> > 	* Makefile.am Add info, dvi, pdf, html targets. On request, copy files to
> > srcdir.
> > 	* Makefile.in: Regenerated.
> > 	* config.h.in: Regenerated.
> > 	* testsuite/Makefile.in: Regenerated.
> > 	* NOTES: Removed.

> I believe there is some bugzilla PR that you are fixing with this patch.
If there are any other PRs but PR28209 that are fixed by this patch,
they are not assigned to component libgomp?!

> Second, do you have an FSF copyright assignment?
The paperwork with FSF is completed, but I do not have write access to svn.

> I can't approve the configury bits.  The documentation looks OK with
> some changes below.  You'll need to have a doc maintainer go over the
> texinfo formatting.
Ok.

Regards
     Daniel

Re: [patch, libgomp, docs] adding documentation to libgomp

[Diego Novillo]

Daniel Franke wrote on 11/29/06 04:36:

> If there are any other PRs but PR28209 that are fixed by this patch,
> they are not assigned to component libgomp?!
> 
Never mind me.  I was thinking of 28209 but failed to see it referenced 
in your ChangeLog entry.

>> Second, do you have an FSF copyright assignment?
> The paperwork with FSF is completed, but I do not have write access to svn.
> 
OK, you can fill the form at 
http://sourceware.org/cgi-bin/pdw/ps_form.cgi and use my address in the 
sponsor field.

Re: [patch, libgomp, docs] adding documentation to libgomp

[Daniel Franke]

[-- Attachment #1: Type: text/plain, Size: 3132 bytes --]


:ADDPATCH libgomp:

On Wednesday 29 November 2006 00:36, Diego Novillo wrote:
> Daniel Franke wrote on 11/23/06 18:09:
> > 2006-11-24  Daniel Franke  <franke.daniel@gmail.com>
> >
> > 	PR libgomp/28209
> > 	* libgomp.texi: New file.
> > 	* configure.ac: Add --enable-generated-files-in-srcdir option.
> > 	* Makefile.am Add info, dvi, pdf, html targets. On request, copy files
> > to srcdir.
> > 	* Makefile.in: Regenerated.
> > 	* config.h.in: Regenerated.
> > 	* testsuite/Makefile.in: Regenerated.
> > 	* NOTES: Removed.
>
> I can't approve the configury bits.  The documentation looks OK with
> some changes below.  You'll need to have a doc maintainer go over the
> texinfo formatting.


Done.

Tested info, dvi, pdf and html targets on i686-pc-linux-gnu.
Please find the revised patch attached and some comments below.

Now waiting for approval of the texinfo/configury parts.

Regards
	Daniel


> > +@menu
> > +* omp_get_dynamic::          Whether Dynamic Teams Are Enabled
> > +* omp_get_max_threads::      Maximum Number Of Threads
> > +* omp_get_nested::           Whether Nested Parallel Regions Are Enabled
> > +* omp_get_num_procs::        Number Of Processors Online
> > +* omp_get_num_threads::      Size Of The Active Team
> > +* omp_get_thread_num::       Current Thread ID
> > +* omp_in_parallel::          Whether A Parallel Region is Active
> > +* omp_set_dynamic::          Enable/Disable Dynamic Teams
> > +* omp_set_nested::           Enable/Disable Nested Parallel Regions
> > +* omp_set_num_threads::      Set Upper Team Size Limit
> > +@end menu
> > +
>
> Does the right column need to be capitalized like that?  It looks
> pretty bad.  Likewise in other menus.

No special reason. Changed the right column, but the beginning of the line and 
abbreviations, to lowercase.


> > +@node omp_set_lock
> > +@section @code{omp_set_lock} -- Wait For And Set Simple Lock
> > +@table @asis
> > +@item @emph{Description}:
> > +Simple locks about to be set must not be uninitialized. The calling
> > thread
>
>    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>    I don't know what you are trying to say here.

This now reads:
"Before setting a simple lock, the lock variable must be initialized by 
@code{omp_init_lock}."



> > +@node omp_unset_lock
> > +@section @code{omp_unset_lock} -- Unset Simple Lock
> > +@table @asis
> > +@item @emph{Description}:
> > +Simple locks about to be unset must not be in a locked state and held by
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> Better move this to the end of the paragraph
>
> > +the thread executing the routine. The lock becomes unlocked. If one ore
> > more
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^  ^^^^^^^^^^^^^^^^^^^^^^^^^
>                                      Non-sequitur.

Ouch. That one was as wrong as it can get.
Now, this reads:
"A simple lock about to be unset must have been locked by @code{omp_set_lock}
or @code{omp_test_lock} before. In addition, the lock must be held by the 
thread calling @code{omp_unset_lock}. Then, the lock becomes unlocked."


Similar changes where made for nested locks.

[-- Attachment #2: libgomp.info.patch.gz --]
[-- Type: application/x-gzip, Size: 9314 bytes --]

Re: [patch, libgomp, docs] adding documentation to libgomp

[Daniel Franke]

On Thursday 30 November 2006 21:58, Daniel Franke wrote:
> > >
> > > 	PR libgomp/28209
> > > 	* libgomp.texi: New file.
> > > 	* configure.ac: Add --enable-generated-files-in-srcdir option.
> > > 	* Makefile.am Add info, dvi, pdf, html targets. On request, copy files
> > > to srcdir.
> > > 	* Makefile.in: Regenerated.
> > > 	* config.h.in: Regenerated.
> > > 	* testsuite/Makefile.in: Regenerated.
> > > 	* NOTES: Removed.
> >

> On Wednesday 29 November 2006 00:36, Diego Novillo wrote:
> > I can't approve the configury bits.  The documentation looks OK with
> > some changes below.  You'll need to have a doc maintainer go over the
> > texinfo formatting.

> Now waiting for approval of the texinfo/configury parts.

*ping*

Re: [patch, libgomp, docs] adding documentation to libgomp

[Daniel Berlin]

On 12/10/06, Daniel Franke <franke.daniel@gmail.com> wrote:
>
> On Thursday 30 November 2006 21:58, Daniel Franke wrote:
> > > >
> > > >   PR libgomp/28209
> > > >   * libgomp.texi: New file.
> > > >   * configure.ac: Add --enable-generated-files-in-srcdir option.
> > > >   * Makefile.am Add info, dvi, pdf, html targets. On request, copy files
> > > > to srcdir.
> > > >   * Makefile.in: Regenerated.
> > > >   * config.h.in: Regenerated.
> > > >   * testsuite/Makefile.in: Regenerated.
> > > >   * NOTES: Removed.
> > >
>
> > On Wednesday 29 November 2006 00:36, Diego Novillo wrote:
> > > I can't approve the configury bits.  The documentation looks OK with
> > > some changes below.  You'll need to have a doc maintainer go over the
> > > texinfo formatting.
>
> > Now waiting for approval of the texinfo/configury parts.
>
> *ping*

Diego, just an FYI, I believe you can approve patches to docs that are
for area you maintain.

Or is it that we just are allowed to modify them.

Gerald, can you clarify (and review this kind person's texinfo formatting)?

>

Re: [patch, libgomp, docs] adding documentation to libgomp

[Diego Novillo]

Daniel Berlin wrote on 12/10/06 20:58:

> Diego, just an FYI, I believe you can approve patches to docs that are
> for area you maintain.
> 
> Or is it that we just are allowed to modify them.
> 
Thanks.  My understanding was option (b), but it would be good if we 
could also approve these patches.

> Gerald, can you clarify (and review this kind person's texinfo formatting)?
> 
Yes, please.

Re: [patch, libgomp, docs] adding documentation to libgomp

[Daniel Franke]

On Monday 11 December 2006 14:20, Diego Novillo wrote:

> Daniel Berlin wrote on 12/10/06 20:58:
> > Diego, just an FYI, I believe you can approve patches to docs that are
> > for area you maintain.
> >
> > Or is it that we just are allowed to modify them.
>
> Thanks.  My understanding was option (b), but it would be good if we
> could also approve these patches.
>
> > Gerald, can you clarify (and review this kind person's texinfo
> > formatting)?
>
> Yes, please.

*ping*

Any news here?

Re: [patch, libgomp, docs] adding documentation to libgomp

[Diego Novillo]

Daniel Berlin wrote on 12/10/06 20:58:

> Diego, just an FYI, I believe you can approve patches to docs that are
> for area you maintain.
> 
> Or is it that we just are allowed to modify them.
> 
> Gerald, can you clarify (and review this kind person's texinfo formatting)?
> 
Daniel just pointed out to me this paragraph from 
http://gcc.gnu.org/svnwrite.html

"Maintainers of a port maintain the files in config/port/, the configure
fragments for the port, documentation for the port and test cases for
                         ^^^^^^^^^^^^^^^^^^^^^^^^^^
features or bugs specific to this port. Port maintainers do not have 
approval rights in other files."

I think that solves the issue.  Daniel, your patch is fine.  If I 
overstepped any boundaries, maybe we should clarify this a bit more.

Re: [patch, libgomp, docs] adding documentation to libgomp

[Gerald Pfeifer]

Hi Diego,

On Thu, 21 Dec 2006, Diego Novillo wrote:
> Daniel just pointed out to me this paragraph from
> http://gcc.gnu.org/svnwrite.html
> 
> "Maintainers of a port maintain the files in config/port/, the configure
> fragments for the port, documentation for the port and test cases for
>                         ^^^^^^^^^^^^^^^^^^^^^^^^^^
> features or bugs specific to this port. Port maintainers do not have approval
> rights in other files."
> 
> I think that solves the issue.  Daniel, your patch is fine.  If I 
> overstepped any boundaries, maybe we should clarify this a bit more.

you did not overstep any boundaries, though libgomp might really qualify 
as a port. :-P

Our documentation in svnwrite.html definitely is somewhat lacking in this 
area, and I'll fix this up in a minute so that it explicitly states that
maintainers can make/approve changes in documentation related to their
areas of maintenance as well, not just code.

Thanks for raising this!

Gerald