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 <j...@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@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-boun...@mcs.anl.gov> on behalf of Patrick Sanan >> via petsc-dev <petsc-dev@mcs.anl.gov> >> Reply-To: Patrick Sanan <patrick.sa...@gmail.com> >> Date: Wednesday, 12 June 2019 at 10:10 >> To: "Smith, Barry F." <bsm...@mcs.anl.gov> >> Cc: petsc-dev <petsc-dev@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.sa...@gmail.com<mailto:patrick.sa...@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. >> <bsm...@mcs.anl.gov<mailto:bsm...@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@mcs.anl.gov<mailto:petsc-dev@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
