[petsc-dev] concern about manpage example listings

[Patrick Sanan]

Great - I volunteer to make a tentative list of KSP tutorials to move to
tests (and hopefully others could follow with SNES, TS, etc.). I'll post
the list as an issue to get any feedback about examples to save, before
doing the twiddling to make a PR.

Am Mo., 22. Apr. 2019 um 08:55 Uhr schrieb Smith, Barry F. <
bsmith at mcs.anl.gov>:

>
>    I'd be happy to see pull requests that transfer the worst examples over
> to the test directory (and their output files!)
>
>    I suspect different people may think different examples are worst but
> this could be sorted in a first pull request that move the worst of the
> worst
>
>
>   Barry
>
> > On Apr 21, 2019, at 12:11 PM, Hapla Vaclav <vaclav.hapla at erdw.ethz.ch>
> wrote:
> >
> >
> >
> >> On 21 Apr 2019, at 11:29, Patrick Sanan <patrick.sanan at gmail.com>
> wrote:
> >>
> >> The quickest fix would of course be to remove that limit. Some pages
> would probably end up with dozens of example links, but that might not be
> so bad, as below are only "implementations" (which are probably used mainly
> by (potential) developers), and links back to the indices. With some
> scripting one could make an html table (or whatever) to have more than one
> link per line to save space.
> >
> > I agree with all, except I think a list is more clear than a table even
> though it is long. I think the space is not an issue as everything relevant
> for basic users is above.
> >
> > I would even suggest to include a separate subsection with tests. Some
> advanced routines might appear only there and it's still better to have a
> list of tests than nothing.
> >
> >>
> >> It would also be helpful to move some of the "bad" examples (which look
> more like tests in many cases) to the tests/ directories.
> >> There are papers out there which reference these examples, but those
> would of course be expected to be the "good" ones.
> >
> > I feel that it's a chronic problem. Some tutorials should already be
> tests because they already cover so many cases that they are becoming
> really cluttered. In this case we could copy the tutorial to tests and keep
> only a stripped-down, more didactic version in tutorials. Is this
> considered a right way?
> >
> >>
> >> Out of curiosity, is there any non-historical argument to have this
> sort of logic in bash, as opposed to python?
> >>
> >>
> >> Am Sa., 20. Apr. 2019 um 23:37 Uhr schrieb Smith, Barry F. via
> petsc-dev <petsc-dev at mcs.anl.gov>:
> >>
> >>    Yeah this is done in lib/petsc/conf/rules
> >>
> >> #
> >> #   Example usage for manual pages; adds each example that uses a
> function to that functions
> >> # manual page up to a limit of 10 examples.
> >> #
> >> manexamples:
> >>         - at base=`basename ${LOCDIR}`; \
> >>         if [ "$${base}" = "tutorials" ] ; then \
> >>           echo "Generating manual example links" ; \
> >>           for i in ${EXAMPLESC} ${EXAMPLESF} foo ; do \
> >>             if [ "$$i" != "foo" ] ; then \
> >>               a=`cat $$i | ${MAPNAMES} -map
> ${LOC}/docs/manualpages/manualpages.cit \
> >>                    -printmatch-link -o /dev/null| cut -f 2 | cut -d '#'
> -f 1 |sed -e s~^../~~ | grep \\.html$$ | sort | uniq` ;  \
> >>               for j in $$a ; do \
> >>                 b=`ls ${LOC}/docs/manualpages/$${j} | grep -v /all/ |
> cut -f9` ; \
> >>                 l=`grep "^<A HREF=\"\.\./\.\./\.\..*/tutorials/" $${b}
> | wc -l`; \
> >>                 if [ $$l -le 10 ] ; then \
> >>                   if [ $$l -eq 0 ] ; then \
> >>                     echo "<P><H3><FONT
> COLOR=\"#CC3333\">Examples</FONT></H3>" >> $$b; \
> >>                   fi; \
> >>                   echo  "<A HREF=\"../../../BB\">BB</A><BR>" | sed
> s?BB?${LOCDIR}$$i.html?g >> $$b; \
> >>                   grep -v /BODY $$b > ltmp; \
> >>                   echo "</BODY></HTML>" >> ltmp; \
> >>                   mv -f ltmp $$b; \
> >>                 fi; \
> >>               done; \
> >>             fi; \
> >>           done; \
> >>         fi
> >>
> >> It has a hardwired limit of 10 (though it seems to produce 11 :-).
> >>
> >> Given how many bad examples we have in the tutorial directories it is
> not a good model to just grab 10 of them.
> >>
> >>
> >>
> >> > On Apr 20, 2019, at 3:49 AM, Hapla Vaclav via petsc-dev <
> petsc-dev at mcs.anl.gov> wrote:
> >> >
> >> > Hello
> >> >
> >> > Why
> >> >
> https://www.mcs.anl.gov/petsc/petsc-dev/docs/manualpages/SNES/SNESSolve.html#SNESSolve
> >> >
> https://www.mcs.anl.gov/petsc/petsc-dev/docs/manualpages/SNES/SNESSetDM.html#SNESSetDM
> >> > do not list ex62 and ex77
> >> >
> https://www.mcs.anl.gov/petsc/petsc-dev/src/snes/examples/tutorials/ex62.c.html
> >> >
> https://www.mcs.anl.gov/petsc/petsc-current/src/snes/examples/tutorials/ex77.c.html
> >> > while these examples use these routines?
> >> >
> >> > It affects both dev and current manpages. Is there a deliberate limit
> on number of examples listed?
> >> >
> >> > I think it's confusing. Particularly these examples are often used in
> tutorials, right?
> >> >
> >> > Thanks,
> >> > Vaclav
> >>
> >
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mcs.anl.gov/pipermail/petsc-dev/attachments/20190422/3b131e37/attachment.html>