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

[Patrick Sanan]

I've just learned to use google or, when offline, to go to my local version
of
https://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/singleindex.html
and use command-F. The doxygen search box is nice, though - if we want
that, do we have to commit to also using Doxygen for the manual?

Am Mi., 12. Juni 2019 um 15:43 Uhr schrieb Smith, Barry F. <
bsmith at mcs.anl.gov>:

>
>   Oana had the very legitimate complaint that we don't have search box for
> manual pages etc. One advantage of "post-processing" the manual pages to
> something like Doxygen is that I think you get nice searchs (you start
> typing and it makes suggestions) "for free". Otherwise do people have
> suggestions on how to set up a good search box (not one that just goes to
> google :-))
>
>
>
>
> > On Jun 12, 2019, at 7:53 AM, Jed Brown <jed at jedbrown.org> wrote:
> >
> > 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/823f42e3/attachment-0001.html>