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

[Jed Brown]

I also use singleindex.  Sphinx can do substring matching and wildcards,
but I don't think autocomplete support exists (which is surprising given
that there's an obvious need and the developers must know how to
implement it).

Patrick Sanan <patrick.sanan at gmail.com> writes:

> 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
>>
>>