[petsc-dev] concern about manpage example listings

[Smith, Barry F.]

   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
>> 
>