[petsc-dev] concern about manpage example listings

[Patrick Sanan]

Here's an issue proposing KSP tutorial examples to move to test examples.
After resolving any comments on this, I'll make a PR to move the
files/output (and perhaps clean up some other things I noticed while going
through these):

https://bitbucket.org/petsc/petsc/issues/272/ksp-examples-tutorials-tests

Am Mo., 22. Apr. 2019 um 10:18 Uhr schrieb Patrick Sanan <
patrick.sanan at gmail.com>:

> 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/9cf7af50/attachment-0001.html>