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.
<[email protected]<mailto:[email protected]>> wrote:
On Jun 15, 2019, at 11:57 AM, Patrick Sanan
<[email protected]<mailto:[email protected]>> 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.
<[email protected]<mailto:[email protected]>>:
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
<[email protected]<mailto:[email protected]>> 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)
