Cool - a patch from master is attached which adds a section to the dev manual, and updates the link to the Sowing docs.
I added the "Concepts" and "Keywords" sections to the list, but I'm not sure if those are currently used in the docs. Also on a branch here: https://bitbucket.org/psanan/petsc/branch/psanan/doc-manpage-format On Sat, Jun 18, 2016 at 3:52 AM, Barry Smith <[email protected]> wrote: > > Patrick, > > Looks pretty complete to me. > > Thanks > > Barry > >> On Jun 17, 2016, at 8:23 AM, Patrick Sanan <[email protected]> wrote: >> >> On Fri, Jun 17, 2016 at 12:18 AM, Barry Smith <[email protected]> wrote: >>> >>> There is a lot going on currently to enhance the PETSc "testing" >>> infrastructure; in particular Lisandro has begun to set up stuff on both >>> github and bitbucket. >>> >>> I've update the PETSc "Dashboard" for testing at >>> ftp://ftp.mcs.anl.gov/pub/petsc/nightlylogs/index.html with more links and >>> a bit more context so people can understand it better. I would like links >>> to other high-level packages testing dashboards such as SLEPc so if you >>> know any send them to me. >>> >>> Here "testing" does not just mean running the test suite but also means >>> collecting gcov information, running static analyzers on the code, running >>> with valgrind, controlling symbol visibility and anything else you can >>> think of that helps detect bugs and flaws in the software. For example >>> tools that automatically check that all visible symbols had manual pages >>> and reported problems, manual pages were complete, etc would be good >>> additions. Currently we rely to much on the kindness of strangers who >>> report bugs in our documentation. >>> >>> Comments, input? >> Re the man pages, here's a draft checklist of things that should be >> there - what's missing? An idea (which I'm happy to implement) is to >> add a section to the dev manual stating what is required and >> recommended to be on each man page. Having that codified would be a >> first step to (semi-)automated maintenance. >> >> Standard Data >> >> - Function name >> - Brief summary >> - "Collectivity" >> - Input and Output parameters (if any) >> - Level >> - Keywords >> - See Also (and if appropriate, symmetrize so that linked pages point back) >> >> Additional Data, if appropriate >> >> - Longer description >> - If there are any relevant output parameters, is the user responsible >> for freeing (or not freeing) something? >> - References to manual or other docs >> - References to literature >> - Fortran-specific information >> - Options Database Keys >> >> Check formatting and links >> >> - Sowing formatting correct (see Dev manual for different special >> comment syntax)? >> - Synopsis and signature correct? >> - Covered by a tutorial example (in .../examples/tutorials/)? >> - Text grammatically correct? >> - Automatic links to other man pages, source, etc. in place correctly? >> >> >>> >>> Barry >>> >>> Currently this file is under RCS on the MCS filesystem, if others would >>> like to contribute to it I'll put it under git at bitbucket. >
0001-Dev-manual-add-subsection-on-expected-fields-for-man.patch
Description: Binary data
