May 2021 - petsc-dev - mailman3.cels.anl.gov

Re: [petsc-dev] [petsc-users] strange segv
by Mark Adams 29 May '21

29 May '21

And I grief using gcc-8.1.1 and get this error: /autofs/nccs-svm1_sw/summit/gcc/8.1.1/include/c++/8.1.1/type_traits(347): error: identifier "__ieee128" is undefined Any ideas? On Sat, May 29, 2021 at 10:39 PM Mark Adams <mfadams(a)lbl.gov> wrote: > And valgrind sees this. I think the jump to the function is going to the > wrong place. > I'm giving up on PGI but can try newer versions of GCC. (what is the deal > with the range of major releases, 4-10?) > (as I said this looks like an error that a user is getting so I'd like to > figure it out). > > 0 SNES Function norm 4.974994975313e-03 > ==77820== Invalid read of size 4 > ==77820== at 0x7E69068: LandauKokkosJacobian (in > /gpfs/alpine/csc314/scratch/adams/petsc/arch-summit-opt-gnu-kokkos-notpl-cuda10/lib/libpetsc.so.3.015.0) > ==77820== by 0x7C598AF: LandauFormJacobian_Internal (plexland.c:212) > ==77820== by 0x7C728D3: LandauIJacobian (plexland.c:2107) > ==77820== by 0x7C8C26B: TSComputeIJacobian (ts.c:934) > ==77820== by 0x7E28337: SNESTSFormJacobian_Theta (theta.c:1007) > ==77820== by 0x7CBBFD3: SNESTSFormJacobian (ts.c:4415) > ==77820== by 0x7AD84BF: SNESComputeJacobian (snes.c:2824) > ==77820== by 0x7BA945B: SNESSolve_NEWTONLS (ls.c:222) > ==77820== by 0x7AF336F: SNESSolve (snes.c:4769) > ==77820== by 0x7E19D13: TSTheta_SNESSolve (theta.c:185) > ==77820== by 0x7E1A8B7: TSStep_Theta (theta.c:223) > ==77820== by 0x7CB093F: TSStep (ts.c:3571) > ==77820== Address 0x96fff690 is in a --- anonymous segment > ==77820== > [0]PETSC ERROR: > ------------------------------------------------------------------------ > [0]PETSC ERROR: Caught signal number 11 SEGV: Segmentation Violation, > probably memory access out of range > [0]PETSC ERROR: Try option -start_in_debugger or -on_error_attach_debugger > [0]PETSC ERROR: or see > https://www.mcs.anl.gov/petsc/documentation/faq.html#valgrind > [0]PETSC ERROR: or try http://valgrind.org on GNU/linux and Apple Mac OS > X to find memory corruption errors > [0]PETSC ERROR: likely location of problem given in stack below > [0]PETSC ERROR: --------------------- Stack Frames > ------------------------------------ > [0]PETSC ERROR: The EXACT line numbers in the error traceback are not > available. > [0]PETSC ERROR: instead the line number of the start of the function is > given. > [0]PETSC ERROR: #1 LandauKokkosJacobian() at > /gpfs/alpine/csc314/scratch/adams/petsc/src/ts/utils/dmplexlandau/kokkos/landau.kokkos.cxx:272 > > On Sat, May 29, 2021 at 8:46 PM Mark Adams <mfadams(a)lbl.gov> wrote: > >> >> >> On Sat, May 29, 2021 at 7:48 PM Barry Smith <bsmith(a)petsc.dev> wrote: >> >>> >>> I don't see why it is not running the Kokkos check. Here is the rule >>> right below the CUDA rule that is apparently running. >>> >>> check_build: >>> -@echo "Running check examples to verify correct installation" >>> -@echo "Using PETSC_DIR=${PETSC_DIR} and >>> PETSC_ARCH=${PETSC_ARCH}" >>> +@cd src/snes/tutorials >/dev/null; ${OMAKE_SELF} >>> PETSC_ARCH=${PETSC_ARCH} PETSC_DIR=${PETSC_DIR} clean-legacy >>> +@cd src/snes/tutorials >/dev/null; ${OMAKE_SELF} >>> PETSC_ARCH=${PETSC_ARCH} PETSC_DIR=${PETSC_DIR} testex19 >>> +@if [ "${HYPRE_LIB}" != "" ] && [ "${PETSC_WITH_BATCH}" = "" ] >>> && [ "${PETSC_SCALAR}" = "real" ]; then \ >>> cd src/snes/tutorials >/dev/null; ${OMAKE_SELF} >>> PETSC_ARCH=${PETSC_ARCH} PETSC_DIR=${PETSC_DIR} >>> DIFF=${PETSC_DIR}/lib/petsc/bin/petscdiff runex19_hypre; \ >>> fi; >>> +@if [ "${CUDA_LIB}" != "" ] && [ "${PETSC_WITH_BATCH}" = "" ] >>> && [ "${PETSC_SCALAR}" = "real" ]; then \ >>> cd src/snes/tutorials >/dev/null; ${OMAKE_SELF} >>> PETSC_ARCH=${PETSC_ARCH} PETSC_DIR=${PETSC_DIR} >>> DIFF=${PETSC_DIR}/lib/petsc/bin/petscdiff runex19_cuda; \ >>> fi; >>> +@if [ "${KOKKOS_KERNELS_LIB}" != "" ] && [ >>> "${PETSC_WITH_BATCH}" = "" ] && [ "${PETSC_SCALAR}" = "real" ] && [ >>> "${PETSC_PRECISION}" = "double" ] && [ "${MPI_IS_MPIUNI}" = "0" ]; then \ >>> cd src/snes/tutorials >/dev/null; ${OMAKE_SELF} >>> PETSC_ARCH=${PETSC_ARCH} PETSC_DIR=${PETSC_DIR} >>> DIFF=${PETSC_DIR}/lib/petsc/bin/petscdiff runex3k_kokkos; \ >>> fi; >>> >>> Regarding the debugging, if it is just one MPI rank (or even more) >>> with GDB it will trap the error and show the exact line of source code >>> where the error occurred and you can poke around at variables to see if >>> they look corrupt or wrong (for example crazy address in a pointer), I >>> don't know why your debugger is not giving more useful information. >>> >>> >> This is what I did (in DDT). It stopped at the function call and the data >> looked fine. I stepped into the call, but didn't get to it. The signal >> handler was called and I was dead. >> Maybe I did something in my branch. Can't see what, but I keep probing, >> Thanks, >> >> >>> Barry >>> >>> >>> > On May 29, 2021, at 2:16 PM, Mark Adams <mfadams(a)lbl.gov> wrote: >>> > >>> > I am running on Summit with Kokkos-CUDA and I am getting a segv that >>> looks like some sort of a compile/link mismatch. I also have a user with a >>> C++ code that is getting strange segvs when calling MatSetValues with CUDA >>> (I know MatSetValues is not a cupsarse method, but that is the report that >>> I have). I have no idea if these are related but they both involve C -- C++ >>> calls ... >>> > >>> > I started with a clean build (attached) and I ran in DDT. DDT stopped >>> at the call in plexland.c to the KokkosLanau operator. I stepped into this >>> function and then took this screenshot of the stack, with the Kokkos call >>> and PETSc signal handler. >>> > >>> > Make check does not seem to be running Kokkos tests: >>> > >>> > 15:02 adams/landau-mass-opt *= >>> /gpfs/alpine/csc314/scratch/adams/petsc$ make >>> PETSC_DIR=/gpfs/alpine/csc314/scratch/adams/petsc >>> PETSC_ARCH=arch-summit-opt-gnu-kokkos-notpl-cuda10 check >>> > Running check examples to verify correct installation >>> > Using PETSC_DIR=/gpfs/alpine/csc314/scratch/adams/petsc and >>> PETSC_ARCH=arch-summit-opt-gnu-kokkos-notpl-cuda10 >>> > C/C++ example src/snes/tutorials/ex19 run successfully with 1 MPI >>> process >>> > C/C++ example src/snes/tutorials/ex19 run successfully with 2 MPI >>> processes >>> > C/C++ example src/snes/tutorials/ex19 run successfully with cuda >>> > Completed test examples >>> > >>> > Also, I ran this AM with another branch that had not been rebased with >>> main as recently as this branch (adams/landau-mass-opt). >>> > >>> > Any ideas? >>> > <make.log><configure.log><Screen Shot 2021-05-29 at 2.51.00 PM.png> >>> >>>

1 0

Re: [petsc-dev] [petsc-users] strange segv
by Mark Adams 29 May '21

29 May '21

And valgrind sees this. I think the jump to the function is going to the wrong place. I'm giving up on PGI but can try newer versions of GCC. (what is the deal with the range of major releases, 4-10?) (as I said this looks like an error that a user is getting so I'd like to figure it out). 0 SNES Function norm 4.974994975313e-03 ==77820== Invalid read of size 4 ==77820== at 0x7E69068: LandauKokkosJacobian (in /gpfs/alpine/csc314/scratch/adams/petsc/arch-summit-opt-gnu-kokkos-notpl-cuda10/lib/libpetsc.so.3.015.0) ==77820== by 0x7C598AF: LandauFormJacobian_Internal (plexland.c:212) ==77820== by 0x7C728D3: LandauIJacobian (plexland.c:2107) ==77820== by 0x7C8C26B: TSComputeIJacobian (ts.c:934) ==77820== by 0x7E28337: SNESTSFormJacobian_Theta (theta.c:1007) ==77820== by 0x7CBBFD3: SNESTSFormJacobian (ts.c:4415) ==77820== by 0x7AD84BF: SNESComputeJacobian (snes.c:2824) ==77820== by 0x7BA945B: SNESSolve_NEWTONLS (ls.c:222) ==77820== by 0x7AF336F: SNESSolve (snes.c:4769) ==77820== by 0x7E19D13: TSTheta_SNESSolve (theta.c:185) ==77820== by 0x7E1A8B7: TSStep_Theta (theta.c:223) ==77820== by 0x7CB093F: TSStep (ts.c:3571) ==77820== Address 0x96fff690 is in a --- anonymous segment ==77820== [0]PETSC ERROR: ------------------------------------------------------------------------ [0]PETSC ERROR: Caught signal number 11 SEGV: Segmentation Violation, probably memory access out of range [0]PETSC ERROR: Try option -start_in_debugger or -on_error_attach_debugger [0]PETSC ERROR: or see https://www.mcs.anl.gov/petsc/documentation/faq.html#valgrind [0]PETSC ERROR: or try http://valgrind.org on GNU/linux and Apple Mac OS X to find memory corruption errors [0]PETSC ERROR: likely location of problem given in stack below [0]PETSC ERROR: --------------------- Stack Frames ------------------------------------ [0]PETSC ERROR: The EXACT line numbers in the error traceback are not available. [0]PETSC ERROR: instead the line number of the start of the function is given. [0]PETSC ERROR: #1 LandauKokkosJacobian() at /gpfs/alpine/csc314/scratch/adams/petsc/src/ts/utils/dmplexlandau/kokkos/landau.kokkos.cxx:272 On Sat, May 29, 2021 at 8:46 PM Mark Adams <mfadams(a)lbl.gov> wrote: > > > On Sat, May 29, 2021 at 7:48 PM Barry Smith <bsmith(a)petsc.dev> wrote: > >> >> I don't see why it is not running the Kokkos check. Here is the rule >> right below the CUDA rule that is apparently running. >> >> check_build: >> -@echo "Running check examples to verify correct installation" >> -@echo "Using PETSC_DIR=${PETSC_DIR} and PETSC_ARCH=${PETSC_ARCH}" >> +@cd src/snes/tutorials >/dev/null; ${OMAKE_SELF} >> PETSC_ARCH=${PETSC_ARCH} PETSC_DIR=${PETSC_DIR} clean-legacy >> +@cd src/snes/tutorials >/dev/null; ${OMAKE_SELF} >> PETSC_ARCH=${PETSC_ARCH} PETSC_DIR=${PETSC_DIR} testex19 >> +@if [ "${HYPRE_LIB}" != "" ] && [ "${PETSC_WITH_BATCH}" = "" ] >> && [ "${PETSC_SCALAR}" = "real" ]; then \ >> cd src/snes/tutorials >/dev/null; ${OMAKE_SELF} >> PETSC_ARCH=${PETSC_ARCH} PETSC_DIR=${PETSC_DIR} >> DIFF=${PETSC_DIR}/lib/petsc/bin/petscdiff runex19_hypre; \ >> fi; >> +@if [ "${CUDA_LIB}" != "" ] && [ "${PETSC_WITH_BATCH}" = "" ] >> && [ "${PETSC_SCALAR}" = "real" ]; then \ >> cd src/snes/tutorials >/dev/null; ${OMAKE_SELF} >> PETSC_ARCH=${PETSC_ARCH} PETSC_DIR=${PETSC_DIR} >> DIFF=${PETSC_DIR}/lib/petsc/bin/petscdiff runex19_cuda; \ >> fi; >> +@if [ "${KOKKOS_KERNELS_LIB}" != "" ] && [ "${PETSC_WITH_BATCH}" >> = "" ] && [ "${PETSC_SCALAR}" = "real" ] && [ "${PETSC_PRECISION}" = >> "double" ] && [ "${MPI_IS_MPIUNI}" = "0" ]; then \ >> cd src/snes/tutorials >/dev/null; ${OMAKE_SELF} >> PETSC_ARCH=${PETSC_ARCH} PETSC_DIR=${PETSC_DIR} >> DIFF=${PETSC_DIR}/lib/petsc/bin/petscdiff runex3k_kokkos; \ >> fi; >> >> Regarding the debugging, if it is just one MPI rank (or even more) with >> GDB it will trap the error and show the exact line of source code where the >> error occurred and you can poke around at variables to see if they look >> corrupt or wrong (for example crazy address in a pointer), I don't know why >> your debugger is not giving more useful information. >> >> > This is what I did (in DDT). It stopped at the function call and the data > looked fine. I stepped into the call, but didn't get to it. The signal > handler was called and I was dead. > Maybe I did something in my branch. Can't see what, but I keep probing, > Thanks, > > >> Barry >> >> >> > On May 29, 2021, at 2:16 PM, Mark Adams <mfadams(a)lbl.gov> wrote: >> > >> > I am running on Summit with Kokkos-CUDA and I am getting a segv that >> looks like some sort of a compile/link mismatch. I also have a user with a >> C++ code that is getting strange segvs when calling MatSetValues with CUDA >> (I know MatSetValues is not a cupsarse method, but that is the report that >> I have). I have no idea if these are related but they both involve C -- C++ >> calls ... >> > >> > I started with a clean build (attached) and I ran in DDT. DDT stopped >> at the call in plexland.c to the KokkosLanau operator. I stepped into this >> function and then took this screenshot of the stack, with the Kokkos call >> and PETSc signal handler. >> > >> > Make check does not seem to be running Kokkos tests: >> > >> > 15:02 adams/landau-mass-opt *= /gpfs/alpine/csc314/scratch/adams/petsc$ >> make PETSC_DIR=/gpfs/alpine/csc314/scratch/adams/petsc >> PETSC_ARCH=arch-summit-opt-gnu-kokkos-notpl-cuda10 check >> > Running check examples to verify correct installation >> > Using PETSC_DIR=/gpfs/alpine/csc314/scratch/adams/petsc and >> PETSC_ARCH=arch-summit-opt-gnu-kokkos-notpl-cuda10 >> > C/C++ example src/snes/tutorials/ex19 run successfully with 1 MPI >> process >> > C/C++ example src/snes/tutorials/ex19 run successfully with 2 MPI >> processes >> > C/C++ example src/snes/tutorials/ex19 run successfully with cuda >> > Completed test examples >> > >> > Also, I ran this AM with another branch that had not been rebased with >> main as recently as this branch (adams/landau-mass-opt). >> > >> > Any ideas? >> > <make.log><configure.log><Screen Shot 2021-05-29 at 2.51.00 PM.png> >> >>

1 0

Re: [petsc-dev] VS Code debugger and PETSc
by Junchao Zhang 29 May '21

29 May '21

I don't have. I think the main problem with petsc is one usually needs to debug with multiple MPI ranks. For light debug, I use gdb or tmpi <https://github.com/Azrael3000/tmpi>; for heavy debug, I use ddt on servers (need license). --Junchao Zhang On Fri, May 28, 2021 at 3:14 PM Aagaard, Brad T via petsc-dev < petsc-dev(a)mcs.anl.gov> wrote: > Does anyone have any experience getting -start_in_debugger to launch the > debugger integrated into VS Code? > > > > Thanks, > > Brad > > >

1 0

VS Code debugger and PETSc
by Aagaard, Brad T 28 May '21

28 May '21

Does anyone have any experience getting -start_in_debugger to launch the debugger integrated into VS Code? Thanks, Brad

1 0

Re: [petsc-dev] links from manual pages to users manual
by Jed Brown 27 May '21

27 May '21

Patrick Sanan <patrick.sanan(a)gmail.com> writes: >> Am 26.05.2021 um 18:39 schrieb Jed Brown <jed(a)jedbrown.org>: >> >> Patrick Sanan <patrick.sanan(a)gmail.com <mailto:[email protected]>> writes: >> >>>> Am 25.05.2021 um 22:58 schrieb Barry Smith <bsmith(a)petsc.dev>: >>>> >>>> >>>> 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-8485… <https://github.com/executablebooks/MyST-Parser/issues/228#issuecomment-8485…> > > 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). I think it's ready for use (we use it in crikit.science) and I intend to convert libCEED using rst-to-myst as soon as this issue is resolved (or one of us can implement it): https://github.com/executablebooks/rst-to-myst/issues/13 We have lots of equations and clean syntax is a huge selling point of MyST. It will also save us some hackery copying files around (which breaks the edit-this-page links). https://myst-parser.readthedocs.io/en/latest/using/howto.html#include-a-fil…

1 0

Re: [petsc-dev] links from manual pages to users manual
by Patrick Sanan 27 May '21

27 May '21

> Am 26.05.2021 um 18:39 schrieb Jed Brown <jed(a)jedbrown.org>: > > Patrick Sanan <patrick.sanan(a)gmail.com <mailto:[email protected]>> writes: > >>> Am 25.05.2021 um 22:58 schrieb Barry Smith <bsmith(a)petsc.dev>: >>> >>> >>> 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-8485… <https://github.com/executablebooks/MyST-Parser/issues/228#issuecomment-8485…> 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?

1 0

Re: [petsc-dev] links from manual pages to users manual
by Patrick Sanan 27 May '21

27 May '21

> Am 27.05.2021 um 00:24 schrieb Barry Smith <bsmith(a)petsc.dev>: > > > > Jed pointed out previously that ideally we would not just generate a million pages of .rst or markdown but we would have the structure of a manual page as an abstract object on which one could write code to validate, to add new information and to output in a particular .rst or markdown. But the abstract object is what we would use to check that all manual pages have the information they need and suitable seealso: etc. I would think doing this in Python (maybe using parts of a Python front end to LLVM to do the function call parsing?) would make sense but are we really going to have the time to design the object, write a decent parser and write the printers? Sowing doesn't really have the abstract object concept, it is local in that reads in a stream and outputs what it finds almost immediately instead of building a complete intermediate form. With this intermediate form generating Fortran, Python, other language binds should be relatively easy and could handle things like character arguments, function pointer arguments etc better. The intermediate form would know which arguments are optional etc. In a sense this intermediate form could define the PETSc API (for functions, structures, enums, macros,...). > > But this sounds a bit PETSc future, we can still improve things with our current infrastructure. Yes, so I think you're suggesting that we add some more processing of the current man pages, which allows insertion of links to pages in the Sphinx docs. > > Sorry, I was not clear, all function names, enums etc in the users manual were automatically replaced with a link to the manual page. Can we do that with Spinx, seems like not to much to ask for. > I think that the standard way to do it with Sphinx involves something like :func:`function_name` which isn't very automatic, so for that reason and because our man pages are generated separately, we currently have our custom plugin which adds the links in code snippets (for HTML only, not in the PDF), using the "htmlmap" generated by the "classic" docs build. My hope is that we could modify the plugin to create the correct internal links, once man pages are better integrated. > Barry > > > > > > >> On May 26, 2021, at 11:36 AM, Patrick Sanan <patrick.sanan(a)gmail.com> wrote: >> >> >> >>> Am 25.05.2021 um 22:58 schrieb Barry Smith <bsmith(a)petsc.dev>: >>> >>> >>> 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 >> - 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? >

1 0

Re: [petsc-dev] links from manual pages to users manual
by Barry Smith 26 May '21

26 May '21

Jed pointed out previously that ideally we would not just generate a million pages of .rst or markdown but we would have the structure of a manual page as an abstract object on which one could write code to validate, to add new information and to output in a particular .rst or markdown. But the abstract object is what we would use to check that all manual pages have the information they need and suitable seealso: etc. I would think doing this in Python (maybe using parts of a Python front end to LLVM to do the function call parsing?) would make sense but are we really going to have the time to design the object, write a decent parser and write the printers? Sowing doesn't really have the abstract object concept, it is local in that reads in a stream and outputs what it finds almost immediately instead of building a complete intermediate form. With this intermediate form generating Fortran, Python, other language binds should be relatively easy and could handle things like character arguments, function pointer arguments etc better. The intermediate form would know which arguments are optional etc. In a sense this intermediate form could define the PETSc API (for functions, structures, enums, macros,...). But this sounds a bit PETSc future, we can still improve things with our current infrastructure. Sorry, I was not clear, all function names, enums etc in the users manual were automatically replaced with a link to the manual page. Can we do that with Spinx, seems like not to much to ask for. Barry > On May 26, 2021, at 11:36 AM, Patrick Sanan <patrick.sanan(a)gmail.com> wrote: > > > >> Am 25.05.2021 um 22:58 schrieb Barry Smith <bsmith(a)petsc.dev>: >> >> >> 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 > - 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?

1 0

Re: [petsc-dev] links from manual pages to users manual
by Jed Brown 26 May '21

26 May '21

Patrick Sanan <patrick.sanan(a)gmail.com> writes: >> Am 25.05.2021 um 22:58 schrieb Barry Smith <bsmith(a)petsc.dev>: >> >> >> 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-8485… > - 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?

1 0

Re: [petsc-dev] links from manual pages to users manual
by Patrick Sanan 26 May '21

26 May '21

> Am 25.05.2021 um 22:58 schrieb Barry Smith <bsmith(a)petsc.dev>: > > > 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 - 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?

1 0