[petsc-dev] User(s) manual sections field in manual pages?

[Patrick Sanan]

It'd be huge if pandoc can do the heavy lifting of converting the manual to
a human-readable-yet-html-renderable format. As a stopgap, particularly
ornery sections of latex could perhaps be compiled as standalone pdfs and
included.

.rst seems like a reasonably safe choice. So many projects use it
(including the linux kernel, moving away from bookdown, says wikipedia)
that it seems unlikely to go away any time soon. What firedrake has looks
pretty gorgeous.

An advantage of a parser for the sowing man pages is that it could also be
used to check/enforce rules, like checking the symmetry of the .seealso
graph (Note again this man-page walking script that Scott already wrote:
https://bitbucket.org/petsc/petsc/commits/53db19705a7bf2d1838cb64c11c1e5ab5997e81d
)


Am Mi., 12. Juni 2019 um 14:53 Uhr schrieb Jed Brown <jed at jedbrown.org>:

> Thanks for starting this thread, Patrick.  For the users manual, my plan
> is to do some mild cleanup so that pandoc can convert it to Markdown or
> rST.  From there, the two systems I'm familiar with are Sphinx and
> Bookdown.  Everyone has seen Sphinx output on readthedocs sites.
> Bookdown is fast and produces results like this (plus PDF and ePUB):
>
>   https://mc-stan.org/docs/2_19/reference-manual/
>
> Either way, I'll need to write a parser for Sowing man pages (in Python
> because that's what people are familiar with and have installed).  I'm
> not wild about converting all the man pages (in source files) to a
> "standard" format (of which Doxygen is the most popular for C and C++)
> because that would be a ton of churn for little benefit and I think
> Doxygen syntax is no better than Sowing.
>
> My rough estimate is that Sphinx would take less work/customization than
> Bookdown for the man pages, but more work for the users manual.
>
> I'd be interested to hear further thoughts.
>
> "Ham, David A via petsc-dev" <petsc-dev at mcs.anl.gov> writes:
>
> > Firedrake is a very happy Sphinx user. Of course our primary language is
> Python. I’m not sure how wonderful sphinx is if your primary language is C
> (though support is, I believe, claimed).
> >
> > From: petsc-dev <petsc-dev-bounces at mcs.anl.gov> on behalf of Patrick
> Sanan via petsc-dev <petsc-dev at mcs.anl.gov>
> > Reply-To: Patrick Sanan <patrick.sanan at gmail.com>
> > Date: Wednesday, 12 June 2019 at 10:10
> > To: "Smith, Barry F." <bsmith at mcs.anl.gov>
> > Cc: petsc-dev <petsc-dev at mcs.anl.gov>
> > Subject: Re: [petsc-dev] User(s) manual sections field in manual pages?
> >
> > (and another potential option is to use a tool to convert the current
> latex source or rendered pdf to HTML)
> >
> > Am Mi., 12. Juni 2019 um 09:40 Uhr schrieb Patrick Sanan <
> patrick.sanan at gmail.com<mailto:patrick.sanan at gmail.com>>:
> > I'm interested to hear more about this plan to refactor the user's
> manual! In particular, is there a concensus on what's a good alternative to
> LaTeX?
> >
> > I got to chat with one of the developers of deal.ii yesterday, which was
> cool - this is of course an example of high quality documentation, and uses
> Doxygen. We've also discussed Sphinx and Madoko in the past. It's also not
> out of the question to avoid heavy dependencies and consider something
> custom, akin to the current HTML generation approach for the man pages and
> other docs on the website.
> >
> > Am Sa., 8. Juni 2019 um 09:33 Uhr schrieb Smith, Barry F. <
> bsmith at mcs.anl.gov<mailto:bsmith at mcs.anl.gov>>:
> >
> >   This was one of my many dreams. The sections in the users manual would
> have latex names and each man page would link to appropriate ones. Given
> the hopelessness of linking inside PDF documents on the web (in theory it
> is possible but no browsers support it) I gave up on it. You can remove
> these. With Jed's plans this summer to refactor the users manual to not use
> latex this all becomes possible but we'll want some automated way of doing
> this, not requiring listing links on each manual page.
> >
> >    Barry
> >
> >
> >> On Jun 8, 2019, at 1:09 AM, Mills, Richard Tran via petsc-dev <
> petsc-dev at mcs.anl.gov<mailto:petsc-dev at mcs.anl.gov>> wrote:
> >>
> >> Colleagues,
> >>
> >> I have noticed that we have a "Users manual sections" section in the
> MatNullSpaceCreate() manual page, and an empty "User manual sections"
> section (which I suppose should be corrected to "Users manual sections",
> since it is officially the "PETSc Users Manual"). Those appear to be the
> only two manual pages that use these headings. Would we like to add these
> for other manual pages, or, since they appear to be unused, should we
> eliminate them?
> >>
> >> --Richard
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mcs.anl.gov/pipermail/petsc-dev/attachments/20190612/1a805474/attachment.html>