split manual 76.2.1 into two subsections #1877

cdwensley · 2017-11-08T18:58:19Z

This PR started out as a comment on #484 (adding guidelines for package authors from Example package). It replaces the attempt which went badly wrong yesterday. It makes changes to sections 76.1 and 76.2 of the reference manual: (a) splitting the LoadPackage section in two, with a separate subsection on automatic loading; (b) removes some duplication; (c) rephrases some passages.

cdwensley · 2017-11-08T19:58:56Z

By the way, are there really any packages which do the following?
A &GAP; package may also automatically install just its documentation,
but still need loading by LoadPackage.
In this situation the online help displays (not loaded) in the
header lines of the manual pages belonging to this &GAP; package.

codecov · 2017-11-08T20:15:48Z

Codecov Report

Merging #1877 into master will increase coverage by 0.05%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master    #1877      +/-   ##
==========================================
+ Coverage   63.63%   63.69%   +0.05%     
==========================================
  Files         946      946              
  Lines      283525   284388     +863     
  Branches    12686    12746      +60     
==========================================
+ Hits       180426   181136     +710     
- Misses     100313   100455     +142     
- Partials     2786     2797      +11

Impacted Files	Coverage Δ
src/intobj.h	`81.48% <0%> (-1.13%)`	⬇️
src/sysfiles.c	`30.45% <0%> (-0.94%)`	⬇️
src/saveload.c	`56.1% <0%> (-0.61%)`	⬇️
src/profile.c	`33.21% <0%> (-0.49%)`	⬇️
src/hpc/thread.c	`46.04% <0%> (-0.4%)`	⬇️
src/range.c	`87.39% <0%> (-0.38%)`	⬇️
src/iostream.c	`46.64% <0%> (-0.38%)`	⬇️
src/funcs.c	`77.55% <0%> (-0.25%)`	⬇️
src/gasman.c	`82.61% <0%> (-0.22%)`	⬇️
src/weakptr.c	`82.67% <0%> (-0.2%)`	⬇️
... and 48 more

olexandr-konovalov · 2017-11-08T21:32:38Z

@cdwensley thanks indeed, looks like in former times there was the Autoload component in the PackageDoc component of PackageInfo.g but has been deprecated - the current template/example from https://github.com/gap-packages/example/blob/master/PackageInfo.g has only this:

PackageDoc := rec(
  # use same as in GAP            
  BookName  := "Example",
  # format/extension can be one of .tar.gz, .tar.bz2, -win.zip, .zip.
  ArchiveURLSubset := ["doc"],
  HTMLStart := "doc/chap0.html",
  PDFFile   := "doc/manual.pdf",
  # the path to the .six file used by GAP's help system
  SixFile   := "doc/manual.six",
  # a longer title of the book, this together with the book name should
  # fit on a single text line (appears with the '?books' command in GAP)
  # LongTitle := "Elementary Divisors of Integer Matrices",
  LongTitle := "Example/Template of a GAP Package",
),

Many packages still have that components which is now likely ignored. This should be checked and then the documentation may be updated as appropriate.

ChrisJefferson

I have some comments, but none of them are requirements, if you disagree with them.

ChrisJefferson · 2017-11-09T19:44:32Z

doc/ref/gappkg.xml

-&GAP; distribution already contains all currently redistributed with 
-&GAP; packages in the <F>&GAPDIRNAME;/pkg</F> directory.
+The &GAP; distribution contains, in the <F>&GAPDIRNAME;/pkg</F> 
+directory, all currently available &GAP; packages.


available -> redistributed I think (there are packages not distributed with GAP)

ChrisJefferson · 2017-11-09T19:45:14Z

doc/ref/gappkg.xml

-your &GAP; installation and calling the <C>../bin/BuildPackages.sh</C> script.
+Before a  package can be  used it must  be installed. 
+A standard distribution of &GAP; already contains all the packages 
+currently available with &GAP;. 


Again, maybe currently redistributed

ChrisJefferson · 2017-11-09T19:46:24Z

doc/ref/gappkg.xml

-be able to use some or all external binaries.
+&GAP; root directories (see <Ref Sect="GAP Root Directories"/>). 
+If you don't have access  to the <F>pkg</F>  directory in your main  &GAP; installation you can add private root directories as explained in that section. 
+<P/>


Maybe say in section <Ref Sect="GAP Root Directories"/>, to make clear what "that section" is.

ChrisJefferson · 2017-11-09T19:48:53Z

lib/package.gd

 ##  (see&nbsp;<Ref Func="CompareVersionNumbers"/>).
-##  The argument <A>name</A> is case insensitive.
+##  If the first character is <C>=</C> then only that version will be loaded. 


... first character of version is ...

Thanks for your comments - I now need some git advice.
Before doing any of the suggested editing I did the following:
(1) in master, did: git pull upstream master, then git push origin
(2) git checkout manual76again, then git rebase master
(3) attempted git push origin manual76again , but got error message:
"error: failed to push some refs to 'https://github.com/cdwensley/gap'
hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart." etc.
Looks like I've made another mess of things? Any suggestions?

Whenever you perform a rebase, you will have to add --force to the git push after that.

In general my advice would be to not worry about rebasing and merging master in -- unless your commit interferes with anyone else, it's fine to drift behind slightly.

olexandr-konovalov

Thanks @cdwensley - glad that this gets more attention, and like how you reduced duplications. Made some suggestions.

olexandr-konovalov · 2017-11-09T22:31:02Z

doc/ref/gappkg.xml

 <P/>
-&GAP; packages are written by (groups  of) &GAP; users which may not
+&GAP; packages are written by (groups  of) &GAP; users who may not
 be  members  of the  &GAP;  developer  team. The  responsibility  and


I'd insert "necessarily" between "may not" and "be members"

olexandr-konovalov · 2017-11-09T22:32:52Z

doc/ref/gappkg.xml

-process.
+The &GAP; development team will assist in making any new package 
+suitable for distribution with &GAP;.   
+It is possible to submit a package to a formal refereeing process.


It is possible -> It is also possible

olexandr-konovalov · 2017-11-09T22:37:29Z

doc/ref/gappkg.xml

+&GAP; root directories (see <Ref Sect="GAP Root Directories"/>). 
+If you don't have access  to the <F>pkg</F>  directory in your main  &GAP; installation you can add private root directories as explained in that section. 
+<P/>
+Whenever you download an  archive  of a  &GAP;  package, it will contain a 


Of course, you can clone a repository instead of downloading, and a package which is mot redistributed with GAP may accidentally not have README (or README.txt or README.md) at all...

olexandr-konovalov · 2017-11-09T22:49:46Z

lib/package.gd

+##  suppressed by using the <C>-A</C> command line option 
+##  (see <Ref Sect="Command Line Options" />).
+##  <P/>
+##  A &GAP; package may also automatically install just its documentation, 


Confirm here looking at https://github.com/gap-system/gap/blob/master/lib/package.gi that now we call LoadPackageDocumentation for all not loaded packages, so this should be rewritten accordingly.

(We may update ValidatePackageInfo to show warnings for obsolete components).

After deleting this paragraph added, to the second paragraph of Ch.76, "(When &GAP; is started, LoadPackageDocumentation is called for all packages.)". Note that LoadPackageDocumentation is not currently in the reference manual, but that there is XML text for it starting at line 662 of package.gd.

cdwensley · 2017-11-10T18:28:12Z

Make all requested changes, but see comment above concerning LoadPackageDocumentation.

olexandr-konovalov · 2017-11-10T23:16:56Z

@cdwensley if we are not going to document LoadPackageDocumentation, fine to just enclose it in <C>...</C>.

cdwensley · 2017-11-11T19:35:12Z

Seems ready now to be merged.

olexandr-konovalov · 2017-11-11T19:59:28Z

@cdwensley Thanks. Who will be merging this, perhaps squash it into one commit.

ChrisJefferson approved these changes Nov 9, 2017

View reviewed changes

split manual 76.2.1 into two subsections

d1274ec

olexandr-konovalov requested changes Nov 9, 2017

View reviewed changes

cdwensley force-pushed the manual76again branch from d3544b4 to d1274ec Compare November 10, 2017 17:56

made all requested changes

f755195

olexandr-konovalov approved these changes Nov 11, 2017

View reviewed changes

ChrisJefferson merged commit 36a4ceb into gap-system:master Nov 13, 2017

olexandr-konovalov added the release notes: not needed PRs introducing changes that are wholly irrelevant to the release notes label Dec 13, 2017

cdwensley deleted the manual76again branch April 18, 2018 19:11

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

split manual 76.2.1 into two subsections #1877

split manual 76.2.1 into two subsections #1877

cdwensley commented Nov 8, 2017

cdwensley commented Nov 8, 2017 •

edited

Loading

codecov bot commented Nov 8, 2017 •

edited

Loading

olexandr-konovalov commented Nov 8, 2017

ChrisJefferson left a comment

ChrisJefferson Nov 9, 2017

ChrisJefferson Nov 9, 2017

ChrisJefferson Nov 9, 2017

ChrisJefferson Nov 9, 2017

cdwensley Nov 9, 2017

ChrisJefferson Nov 9, 2017

olexandr-konovalov left a comment

olexandr-konovalov Nov 9, 2017

olexandr-konovalov Nov 9, 2017

olexandr-konovalov Nov 9, 2017

olexandr-konovalov Nov 9, 2017

cdwensley Nov 10, 2017

cdwensley commented Nov 10, 2017

olexandr-konovalov commented Nov 10, 2017

cdwensley commented Nov 11, 2017

olexandr-konovalov commented Nov 11, 2017

split manual 76.2.1 into two subsections #1877

split manual 76.2.1 into two subsections #1877

Conversation

cdwensley commented Nov 8, 2017

cdwensley commented Nov 8, 2017 • edited Loading

codecov bot commented Nov 8, 2017 • edited Loading

Codecov Report

olexandr-konovalov commented Nov 8, 2017

ChrisJefferson left a 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

olexandr-konovalov left a 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

cdwensley commented Nov 10, 2017

olexandr-konovalov commented Nov 10, 2017

cdwensley commented Nov 11, 2017

olexandr-konovalov commented Nov 11, 2017

cdwensley commented Nov 8, 2017 •

edited

Loading

codecov bot commented Nov 8, 2017 •

edited

Loading