[petsc-dev] concern about manpage example listings

[Patrick Sanan]

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.

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.

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/20190421/65bfbc43/attachment.html>