Patrick,
Thanks, make it a pull request to master and I'll merge it right in.
Barry
> On Jun 20, 2016, at 5:54 AM, Patrick Sanan <[email protected]> wrote:
>
> 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>
