Updated package.gd to add examples for LoadPackage command + Punctuation tweak to CONTRIBUTING.md #155

sr-murthy · 2015-04-05T22:33:34Z

No description provided.

sr-murthy · 2015-04-05T22:47:40Z

Hi, the Travis CI build has passed for the latest change to package.gd to add an example for the LoadPackage command. I've used the Sonata package in the example. I hope it's all OK.

olexandr-konovalov · 2015-04-05T23:10:28Z

Thanks. Currently Travis builds do not check that the manual may be built, so passing the test does not ensure this. It is advised to call make manuals in the GAP root directory to check that the manuals may be built. The GAPDoc code looks fine to me, I will make some comments in the source code.

olexandr-konovalov · 2015-04-05T23:13:36Z

lib/package.gd

@@ -691,6 +691,31 @@ DeclareGlobalFunction( "LoadPackageDocumentation" );
 ##
 ##  <Description>
 ##  loads the &GAP; package with name <A>name</A>.
+## <P/>
+##  As an example, the following loads the &GAP; subgroups package


I suggest to use loads the &GAP; package <Package>SONATA</Package> which provides methods for the construction and analysis of finite nearrings:

Would it not be simpler to make Travis check that the manual can be built?

I tried make manuals from the GAP repo root but received the following message

make: *** No rule to make target `manuals'. Stop.

I tried make manuals from the GAP repo root but received the following message

make: *** No rule to make target `manuals'. Stop.

Ah, I was assuming that GAP is built already since you need it to build manuals.
So, the full process from a clean checkout is

./configure
make
make manuals

Yes, of course I had forgotten to configure and make GAP. I'm making the manuals now.

Seems the 'gapdoc' package cannot be accessed by the GAP build in the repo.

Yes. The easiest way to get it working is perhaps to put a symlink pkg in the GAP root directory pointing to the pkg directory from the latest GAP installation.

Would it not be simpler to make Travis check that the manual can be built?

There are several aspects here. Perhaps this should be an enhancement proposal,
not a hidden side note in the commit, but for now I'll put it here:

what do we want to test?
a) that 'make manuals' does not fail (a common case when it fails
is an error in GAPDoc syntax)
b) that there are no unresolved references in the manual
c) that manual examples run as expected (with default selection of packages).

We run nightly tests using Jenkins CI where failures of types
(a) and (c) are detected automatically and trigger build failure.
We may discuss which of these checks we want to have in Travis.
Perhaps at least (a) would be important to have, to check pull
requests related to GAP manuals.

OK it seems to be fine after creating the symlink to /Applications/GAP/gap4r7/pkg/. Here is the output.

make manuals ( echo 'SaveWorkspace( "doc/wsp.g" );' | ./bin/gap-default64.sh -b -m 100m -o 750m -q -x 80 -r ) true ( cd doc/ref; echo 'Read( "makedocrel.g" );' | \ ../.././bin/gap-default64.sh -b -m 100m -o 750m -A -q -x 80 -r -L ../wsp.g > make_manuals.out ) ( cd doc/tut; echo 'Read( "makedocrel.g" );' | \ ../.././bin/gap-default64.sh -b -m 100m -o 750m -A -q -x 80 -r -L ../wsp.g > make_manuals.out ) ( cd doc/changes; echo 'Read( "makedocrel.g" );' | \ ../.././bin/gap-default64.sh -b -m 100m -o 750m -A -q -x 80 -r -L ../wsp.g > make_manuals.out ) ( cd doc/ref; echo 'Read( "makedocrel.g" );' | \ ../.././bin/gap-default64.sh -b -m 100m -o 750m -A -q -x 80 -r -L ../wsp.g > make_manuals.out ) ( cd doc/tut; echo 'Read( "makedocrel.g" );' | \ ../.././bin/gap-default64.sh -b -m 100m -o 750m -A -q -x 80 -r -L ../wsp.g > make_manuals.out ) ( cd doc/changes; echo 'Read( "makedocrel.g" );' | \ ../.././bin/gap-default64.sh -b -m 100m -o 750m -A -q -x 80 -r -L ../wsp.g > make_manuals.out ) ( rm doc/wsp.g )

OK it seems to be fine after creating the symlink to /Applications/GAP/gap4r7/pkg/. Here is the output.

Great! The build log is redirected to make_manuals.out, you may also wish to check those files.

OK, mdfind make_manuals.out shows three versions existing in doc/ref, doc/tut and doc/changes, looks like one each for the reference manual, tutorial and changes.

I've checked all three, and they look OK. I can post the output if you want (about 50 lines in each).

sr-murthy · 2015-04-06T06:32:04Z

Added the LoadPackage examples for Semigroups and Design to package.gd.

olexandr-konovalov · 2015-04-06T09:40:13Z

lib/package.gd

+##  The package name may be appropriately abbreviated as shown in the following
+##  two examples with the &GAP; packages <Package>Semigroups</Package>, for
+##  working with semigroups, monoids and associated structures, and
+##  <Package>Design</Package>, for working with block designs:


The author is using uppercase and writes DESIGN - please follow this style.

OK no problem.

sr-murthy · 2015-04-06T11:43:13Z

OK, make manuals seems fine, and the commit for the latest change is now included in the PR. Hope it addresses all the outstanding issues.

olexandr-konovalov · 2015-04-07T09:38:04Z

lib/package.gd

@@ -691,6 +691,31 @@ DeclareGlobalFunction( "LoadPackageDocumentation" );
 ##
 ##  <Description>
 ##  loads the &GAP; package with name <A>name</A>.
+## <P/>
+##  As an example, the following loads the &GAP; package
+## <Package>Sonata</Package> (case insensitive) which provides methods for the


Please correct this to <Package>SONATA</Package> to match the style chosen by authors. This will also trigger new Travis build which now includes making GAP manuals.

olexandr-konovalov · 2015-04-07T10:43:10Z

lib/package.gd

+##  working with semigroups, monoids and associated structures, and
+##  <Package>DESIGN</Package>, for working with block designs:
+##  <P/>
+##  <Log><![CDATA[


I'm afraid that defeats the purpose. I didn't want long banners, but now it's not even clear which package is loaded. I suggested another option yesterday, may we go for it? What about:

The package name may be appropriately abbreviated. For example, <C>LoadPackage("semi");</C> will load the <Package>Semigroups</Package> package, and <C>LoadPackage("d");</C> will load the <Package>DESIGN</Package> package. If the abbreviation can not be uniquely completed, further suggestions will be offered.

OK I will do this later.

olexandr-konovalov · 2015-04-07T22:30:08Z

Great, thanks - the new Travis build checked that the manual may be built. I suggest to merge this PR and close issue #8 then.

Updated package.gd to add examples for LoadPackage command. Also, some minor edits in CONTRIBUTING.md

Sandeep Murthy added 3 commits April 5, 2015 22:37

Punctuation tweak to CONTRIBUTING.md

0c72f50

Punctuation tweak to CONTRIBUTING.md

736de01

Updated package.gd to add example for LoadPackage command

5c8f1e0

olexandr-konovalov reviewed Apr 5, 2015
View reviewed changes

Added further two examples for LoadPackage command

d878b2f

sr-murthy changed the title ~~Updated package.gd to add example for LoadPackage command + Punctuation tweak to CONTRIBUTING.md~~ Updated package.gd to add examples for LoadPackage command + Punctuation tweak to CONTRIBUTING.md Apr 6, 2015

Added line break to overflowing line #719 in package.gd

157e417

olexandr-konovalov reviewed Apr 6, 2015
View reviewed changes

Refined example additions for LoadPackage

bb67fd8

olexandr-konovalov reviewed Apr 7, 2015
View reviewed changes

olexandr-konovalov mentioned this pull request Apr 7, 2015

Type of the first argument of LoadPackage is not specified #8

Closed

olexandr-konovalov reviewed Apr 7, 2015
View reviewed changes

Updated package.gd

ea00f93

olexandr-konovalov pushed a commit that referenced this pull request Apr 8, 2015

Merge pull request #155 from sr-murthy/srm

7d4eb9b

Updated package.gd to add examples for LoadPackage command. Also, some minor edits in CONTRIBUTING.md

olexandr-konovalov merged commit 7d4eb9b into gap-system:master Apr 8, 2015

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Updated package.gd to add examples for LoadPackage command + Punctuation tweak to CONTRIBUTING.md #155

Updated package.gd to add examples for LoadPackage command + Punctuation tweak to CONTRIBUTING.md #155

sr-murthy commented Apr 5, 2015

sr-murthy commented Apr 5, 2015

olexandr-konovalov commented Apr 5, 2015

olexandr-konovalov Apr 5, 2015

sr-murthy Apr 6, 2015

sr-murthy Apr 6, 2015

olexandr-konovalov Apr 6, 2015

sr-murthy Apr 6, 2015

olexandr-konovalov Apr 6, 2015

olexandr-konovalov Apr 6, 2015

sr-murthy Apr 6, 2015

olexandr-konovalov Apr 6, 2015

sr-murthy Apr 6, 2015

sr-murthy commented Apr 6, 2015

olexandr-konovalov Apr 6, 2015

sr-murthy Apr 6, 2015

sr-murthy commented Apr 6, 2015

olexandr-konovalov Apr 7, 2015

sr-murthy Apr 7, 2015

olexandr-konovalov Apr 7, 2015

sr-murthy Apr 7, 2015

olexandr-konovalov commented Apr 7, 2015

Updated package.gd to add examples for LoadPackage command + Punctuation tweak to CONTRIBUTING.md #155

Updated package.gd to add examples for LoadPackage command + Punctuation tweak to CONTRIBUTING.md #155

Conversation

sr-murthy commented Apr 5, 2015

sr-murthy commented Apr 5, 2015

olexandr-konovalov commented Apr 5, 2015

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sr-murthy commented Apr 6, 2015

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sr-murthy commented Apr 6, 2015

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

olexandr-konovalov commented Apr 7, 2015