[petsc-dev] Sowing: proposed change to allow single-entry lists on man pages

Gropp, William D wgropp at illinois.edu
Tue Jun 25 02:05:27 CDT 2019

Thanks for this suggestion.  The + and - were added to make it easier to generate a nicely formatted list, though its possible to look for transitions from non-list to list and back to non-list.  Think of + as similar to \begin{description}\item … and - as \item … \end{description}.

I’ve updated doctext to allow both - and a isolated . for an argument description. In the process of doing this, I added checks for errors in the use of the doctext formatting, and found many minor errors, as well as updating the old arg lists that didn’t use the + .. - . I have a branch for petsc that fixes all of those (it was the easiest way for me to be sure my doctext fixes worked) that will need to be merged.  Let me know how you’d like me to submit that. There are also many malformed entries where there is no description.  I’ve turned those warnings off by default, but -Wargdesc will warn for each argument that is missing a description; some of these should use different formatting instead of the argument lists.

The new version, in sowing-1.1.26, also has updates to bfort (which requires the patch that I sent earlier to bin/maint/generatefortranstubs.py ) and other miscellaneous fixes.  I’ve uploaded this version to my web page and it is the default when you download sowing.tar.gz .  I am unable to update the confdb macros to fix errors in them - the permissions have changed on the repository (for my own files!).  Because of that and other problems, I plan to move sowing to a git repository that I fully control soon; this weekend if I can.

Let me know if you have any problems.


William Gropp
Director and Chief Scientist, NCSA
Thomas M. Siebel Chair in Computer Science
University of Illinois Urbana-Champaign

On Jun 15, 2019, at 12:06 PM, Smith, Barry F. <bsmith at mcs.anl.gov<mailto:bsmith at mcs.anl.gov>> wrote:

On Jun 15, 2019, at 11:57 AM, Patrick Sanan <patrick.sanan at gmail.com<mailto:patrick.sanan at gmail.com>> wrote:

Great! I'll leave that commit there for reference, but as you say it would be even nicer (but more coding) to avoid needing to explicitly mark the starts and ends of lists.

  Yeah, I only remember vaguely that initially we didn't use the + and - on the lists and there was some issue so they were introduced.


Am Sa., 15. Juni 2019 um 17:54 Uhr schrieb Smith, Barry F. <bsmith at mcs.anl.gov<mailto:bsmith at mcs.anl.gov>>:

 Patrick (and Bill)

    Good timing. Bill is actually updating Sowing now and could perhaps fix this glitch. Currently we use a . for a single entry in the list and I'd hate to have to change them all the -. Likely it is possible to fix the formatting for the . case to have the same indent as the + . - cases.


On Jun 15, 2019, at 10:15 AM, Patrick Sanan via petsc-dev <petsc-dev at mcs.anl.gov<mailto:petsc-dev at mcs.anl.gov>> wrote:

Lists on the man pages don't seem to be able to have a single entry, because sowing requires you to start lists with "+" and end them with "-", requiring at least two entries.

This leads to ugly-looking indentation for man pages for functions with a single input or output parameter, e.g. https://www.mcs.anl.gov/petsc/petsc-dev/docs/manualpages/DMSTAG/DMStagVecGetArrayDOF.html

I think that this can be remedied with a small change to sowing (doctext), to interpret a lone '-' as opening a list (and then closing it after one entry): https://bitbucket.org/psanan/sowing/commits/780ea53824388e8c6089ae2d6210332c63935edb

(Posting this here since I'm not sure how closely the bitbucket.org/petsc/pkg-sowing<http://bitbucket.org/petsc/pkg-sowing> repository is monitored)

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mcs.anl.gov/pipermail/petsc-dev/attachments/20190625/7e523a1d/attachment.html>

More information about the petsc-dev mailing list