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

[Smith, Barry F. via petsc-dev]

> On Jun 12, 2019, at 4:08 AM, Patrick Sanan <patrick.sa...@gmail.com> wrote:
> 
> (and another potential option is to use a tool to convert the current latex 
> source or rendered pdf to HTML)

   Those tools are terrible, you get a big ugly mess. 

   Jed is the one with the big plans.

   Barry

> 
> Am Mi., 12. Juni 2019 um 09:40 Uhr schrieb Patrick Sanan 
> <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>:
> 
>   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> 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
>