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

[Balay, Satish]

Bill,

The generic pull request instructions are at:

https://bitbucket.org/petsc/petsc/wiki/Home#markdown-header-contributing-to-petsc
https://bitbucket.org/petsc/petsc/wiki/pull-request-instructions-git

Some of the instructions are wrt a fork. With write access to the
petsc repo - you can create a branch gropp/feature-name, and create a
PR from it.

Satish

On Mon, 1 Jul 2019, Gropp, William D via petsc-dev wrote:

> If someone sends me the instructions, I can create the pull request (my experience with git is that each project has very particular requirements and things go better if I follow each projects specific checklist).
> 
> Bill
> 
> William Gropp
> Director and Chief Scientist, NCSA
> Thomas M. Siebel Chair in Computer Science
> University of Illinois Urbana-Champaign
> 
> 
> 
> 
> 
> 
> On Jun 29, 2019, at 5:50 AM, Patrick Sanan <patrick.sanan at gmail.com<mailto:patrick.sanan at gmail.com>> wrote:
> 
> That's great! That'll go a long way towards making the man pages look neater - I'm happy to review the PR that updates the arg lists on the man pages - is your branch off of master (and thus can be submitted with the usual procedure of a pull request on bitbucket)?
> 
> Am Di., 25. Juni 2019 um 09:05 Uhr schrieb Gropp, William D <wgropp at illinois.edu<mailto:wgropp at illinois.edu>>:
> 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.
> 
> Bill
> 
> 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.
> 
>  Barry
> 
> 
> 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.
> 
>   Barry
> 
> 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)
> 
> 
> 
> 
>