> On Jun 21, 2016, at 2:40 AM, Patrick Sanan <[email protected]> wrote: > > PR #498 made. > > I am also interested in making an edit of the dev manual more broadly. > Are there any unusual restrictions on the latex build on the machine > where the docs are generated?
Unusual? I guess just make your changes and we'll see if anything breaks on the "official doc build machine" Thanks Barry > > On Mon, Jun 20, 2016 at 6:49 PM, Barry Smith <[email protected]> wrote: >> >> 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> >>
