[petsc-dev] concern about manpage example listings

[Smith, Barry F.]

   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