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

[Patrick Sanan]

Looks great!

Am Di., 2. Juli 2019 um 17:06 Uhr schrieb Balay, Satish <balay at mcs.anl.gov>:

> Patrick,
>
> PR is now at:
> https://bitbucket.org/petsc/petsc/pull-requests/1838/fixes-for-doctext-update/diff
>
> Satish
>
>
> On Sat, 29 Jun 2019, Patrick Sanan via petsc-dev 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>:
> >
> > > 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>
> wrote:
> > >
> > >
> > >
> > > On Jun 15, 2019, at 11:57 AM, Patrick Sanan <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>:
> > >
> > >  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> 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 repository is monitored)
> > >
> > >
> > >
> > >
> > >
> >
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mcs.anl.gov/pipermail/petsc-dev/attachments/20190703/22ef1f84/attachment.html>