> Am 26.05.2021 um 18:39 schrieb Jed Brown <[email protected]>: > > Patrick Sanan <[email protected] <mailto:[email protected]>> > writes: > >>> Am 25.05.2021 um 22:58 schrieb Barry Smith <[email protected]>: >>> >>> >>> Now that the users manual is html and we can properly link into it, it >>> would be great to have links from the manual pages to appropriate locations >>> in the users manual. For example SNESSetFunction.html would have a link to >>> the generated Spinx location where SNESSetFunction is discussed. >>> >>> How do we go about doing this? >>> >>> Not only is this useful for users but when developers are fixing/improving >>> a manual page it would be nice if they had a way to jump directly to the >>> appropriate place in the xxx.rst that that discusses the manual page to >>> check that that material is also up-to-date and correct. So I guess we need >>> a way to link to the correct place in the .rst and the generated .html >>> >> This all depends on which approach we take to make the man pages better >> integrated. There are competing requirements so I think it'll have to be >> hashed out to find the correct compromise >> >> - we need to leave things for Sowing to generate Fortran stubs >> - we want to be able to write the man pages as .rst, like the rest of the >> Sphinx docs > > Or Markdown; see recent activity in this issue. > > https://github.com/executablebooks/MyST-Parser/issues/228#issuecomment-848505703 > > <https://github.com/executablebooks/MyST-Parser/issues/228#issuecomment-848505703>
This is cool to know about - if I'm reading this correctly it's not ready for us to immediately adopt, but I don't think you'll find many who like RST more than Markdown, so if there's a good chance to switch from RST to MyST at some point, I think it makes sense (say if there's a robust automatic rst-to-myst convertor, which seems to almost exist <https://github.com/executablebooks/rst-to-myst> now). My hesitancy to do it now comes from RST's privileged status as a the dumb default which you can google about, and not wanting to incrementally introduce MyST because I fear that'll make things worse for people wanting to edit (two new things to learn, can't copy-paste things between the two). > >> - we want the man pages inline with the source >> - we don't want to have to manually update all the man pages >> - we want to avoid introducing brittle scripting, if possible >> >>> >>> Thanks >>> >>> Barry >>> >>> In the old users manual I had it rigged to have a link to the manual page >>> for every occurrence of a word that had a manual page in the users manual. >>> Is that feature lost now? Is there anyway to bring it back? >>> >>> >> >> This is lost, I think. What sorts of words were these? Once we have links >> from the man pages to the manual, as above, would it be just as good to >> directly link to sections of the manual?
