convert Changes manuals book into markdown #3886

dimpase · 2020-02-06T01:44:05Z

Convert Changes manuals book into markdown

Text for release notes

Changed are no longer a Manual's "book", butr just a markdown file

Further details

If necessary, please provide further details here.

Checklist for pull request reviewers

proper formatting

If your code contains kernel C code, run clang-format on it; the
simplest way is to use git clang-format, e.g. like this (don't
forget to commit the resulting changes):

git clang-format $(git merge-base HEAD master)

usage of relevant labels
1. either release notes: not needed or release notes: to be added
2. at least one of the labels bug or enhancement or new feature
3. for changes meant to be backported to stable-4.X add the backport-to-4.X label
4. consider adding any of the labels build system, documentation, kernel, library, tests
runnable tests
lines changed in commits are sufficiently covered by the tests
adequate pull request title
well formulated text for release notes
relevant documentation updates
sensible comments in the code

Merge everything into one file, as well

dimpase · 2020-02-06T08:58:03Z

tests are failing, but nothing to do with this PR

olexandr-konovalov · 2020-02-06T10:06:01Z

Thanks. Others can see rendered markdown at https://github.com/dimpase/gap/blob/master/doc/Changes.md

Questions so far:

filename: Changes.md or CHANGES.md?
location: doc or root directory?

Furthermore, I suspect failing tests are because of this PR:

testing: /home/travis/build/gap-system/gap/tst/teststandard/helptools.tst
########> Diff in /home/travis/build/gap-system/gap/tst/teststandard/helptools\
.tst:7
# Input is:
ForAll(FindMultiSpelledHelpEntries(), i -> 
   Length( Set( List( HELP_SEARCH_ALTERNATIVES( i[3] ), 
                      j -> HELP_SEARCH_ALTERNATIVES(j) ) ) ) = 1 );
# Expected output:
true
# But found:
Error, no method found! For debugging hints type ?Recovery from NoMethodFound
Error, no 1st choice method found for `Filename' on 2 arguments
The 1st argument is 'fail' which might point to an earlier problem
########

since it tried to load the now missing manual book. Other diffs are perhaps of the same reason.

doc/Changes.md

doc/README.md

doc/make_doc.in

fingolfin

Some remarks. Some of these are optional resp. I don't necessarily expect @dimpase to take care of them, I can also push tweaks to this PR.

Many thanks to @dimpase for working on this!

doc/Changes.md

fingolfin · 2020-02-06T14:27:32Z

doc/Changes.md

+    and therefore is no longer distributed with
+**GAP**.
+
+#### 2.2 **GAP** 4.10.1 (February 2019)


So right now the order of releases in this file is:

4.11.0

4.10.0

4.10.1

4.10.2

4.9.0

4.9.1

...

That's not good. We should permute it.

doc/Changes.md

dimpase · 2020-02-06T19:29:27Z

I'm trying to fix the failing test

dimpase · 2020-02-06T19:31:05Z

what the fresh hell is

$ make doc
doc/make_doc
--------------------
Building GAP manuals
--------------------
----------------------------
Building GAP manual 'ref' at /home/dimpase/work/gap/doc/ref
Run 1 of 2
----------------------------
#I Composing XML document . . .
#I Parsing XML document . . .
#I Checking XML structure . . .
#I Text version (also produces labels for hyperlinks):
#I First run, collecting cross references, index, toc, bib and so on . . .
Error, no method found! For debugging hints type ?Recovery from NoMethodFound
Error, no 1st choice method found for `Filename' on 2 arguments
The 1st argument is 'fail' which might point to an earlier problem
 at /home/dimpase/work/gap/lib/methsel2.g:249 called from
make: *** [Makefile.rules:796: doc] Error 1

I'm trying to builf this branch using the packages-stable-4.11 tarball, in case
(and after make distclean)

olexandr-konovalov

Thanks @dimpase for cleaning this up - we have a good progress, hope we can merge this tomorrow and do release wrapping on the weekend. Please change the spelling of the filename to CHANGES.md and put it in the root directory, not where it is now,

dimpase · 2020-02-06T22:08:22Z

do you have any idea why I can't build the doc anymore. I tried on two different boxes...

dimpase · 2020-02-06T22:16:21Z

git bisect, here we come :-)

olexandr-konovalov · 2020-02-06T22:17:09Z

@dimpase yes: go to doc/ref and do this to get a break loop which you can explore:

$ ../../bin/gap.sh -r -A makedocrel.g 
 ┌───────┐   GAP 4.8.4-7480-g5c72952 of today
 │  GAP  │   https://www.gap-system.org
 └───────┘   Architecture: x86_64-apple-darwin18.7.0-default64-kv8
 Configuration:  gmp 6.1.2, GASMAN
 Loading the library and packages ...
 Packages:   GAPDoc 1.6.3, PrimGrp 3.4.0, SmallGrp 1.4.1, TransGrp 2.0.4
 Try '??help' for help. See also '?copyright', '?cite' and '?authors'
#I Composing XML document . . .
#I Parsing XML document . . .
#I Checking XML structure . . .
#I Text version (also produces labels for hyperlinks):
#I First run, collecting cross references, index, toc, bib and so on . . .
Error, no method found! For debugging hints type ?Recovery from NoMethodFound
Error, no 1st choice method found for `Filename' on 2 arguments
The 1st argument is 'fail' which might point to an earlier problem
 at /Users/alexk/GITREPS/dimpase-gap/lib/methsel2.g:249 called from
Filename( dirs, "manual.six" 
 ) at /Users/alexk/GITREPS/dimpase-gap/lib/helpbase.gi:683 called from
HELP_BOOK_INFO( bookname 
 ) at /Users/alexk/GITREPS/dimpase-gap/pkg/GAPDoc-1.6.3/lib/GAPDoc2Text.gi:147\
2 called from
GAPDoc2TextProcs.ResolveExternalRef( r.attributes.BookName, lab, 1 
 ) at /Users/alexk/GITREPS/dimpase-gap/pkg/GAPDoc-1.6.3/lib/GAPDoc2Text.gi:154\
3 called from
GAPDoc2TextProcs.(r.name)( r, str 
 ); at /Users/alexk/GITREPS/dimpase-gap/pkg/GAPDoc-1.6.3/lib/GAPDoc2Text.gi:38\
0 called from
GAPDoc2Text( a, s 
 ); at /Users/alexk/GITREPS/dimpase-gap/pkg/GAPDoc-1.6.3/lib/GAPDoc2Text.gi:49\
3 called from
...  at makedocrel.g:15
type 'quit;' to quit to outer loop
brk> dirs;
fail
brk> bookname;
"changes"
brk>

I think this is due to all cross-references from manuals to bookname="changes" now being unresolved. Perhaps because of some status of the main manual book, instead of leaving them unresolved, it fails more dramatically.

olexandr-konovalov · 2020-02-06T22:20:15Z

@dimpase Hopefully only two places:

$ grep -n -R "\"Changes\"" --include=*.xml doc
doc/ref/preface.xml:23:<Ref BookName="Changes" Label="Preface"/>)</Alt>.
doc/tut/preface.xml:30:<Alt Only="HTML">(see <Ref BookName="Changes" Label="Preface"/>)</Alt>

dimpase · 2020-02-06T22:25:46Z

right, just cleaned these up, testing

olexandr-konovalov · 2020-02-06T23:13:42Z

OK - it's now available for preview at https://github.com/dimpase/gap/blob/master/CHANGES.md

CHANGES.md

fingolfin · 2020-02-09T14:43:48Z

These are historical texts. I would not change URLs or add "UPDATE 2020" links, unless you are willing to commit to check and update ALL links, and during every release. And frankly I'd still be against it because I wouldn't be sure you'd be able to stick to such a commitment for multiple years (no offense intended, I wouldn't trust that with myself either)

dimpase · 2020-02-09T15:47:53Z

let the historians of maths software care about broken URLs - and before this PR they were present too, so that's not a regression to keep it this way.

olexandr-konovalov · 2020-02-09T16:52:06Z

For historians of math software https://archiveprogram.github.com/ says that GAP will go to Svalbard: "The 02/02/2020 snapshot archived in the GitHub Arctic Code Vault will sweep up every active public GitHub repository, in addition to significant dormant repos. The snapshot will include every repo with any commits between the announcement at GitHub Universe on November 13th and 02/02/2020, every repo with at least 1 star and any commits from the year before the snapshot (02/03/2019 - 02/02/2020), and every repo with at least 250 stars."

olexandr-konovalov · 2020-02-10T22:26:17Z

@dimpase if you could address my remarks about the number of manual books and missing mentions of the HPC-GAP manual, perhaps this will be ready for merging...

dimpase · 2020-02-10T22:50:33Z

@alex-konovalov I adjusted the number of books as Changes stopped being one. And adding HPC-GAP as a "new" book probably needs another PR - is there a consensus that it's mature and useful enough on its own to be promoted to this level?

olexandr-konovalov · 2020-02-10T23:43:26Z

@dimpase That book is "official" in a sense that it's linked from https://www.gap-system.org/Doc/manuals.html

dimpase · 2020-02-11T17:55:39Z

@alex-konovalov OK, done

doc/tut/preface.xml

doc/ref/preface.xml

olexandr-konovalov

Looks good - left just one comment about README.md. @fingolfin are you happy to merge?

olexandr-konovalov · 2020-02-11T23:34:23Z

doc/README.md

 respectively. Some documentation is also stored in the library files to be kept 
 close to the code it describes. It is included in the manual using the mechanism 
-documented [here](https://www.gap-system.org/Manuals/pkg/GAPDoc-1.5.1/doc/chap4.html).
+documented [here](https://www.gap-system.org/Manuals/pkg/GAPDoc-1.6.2/doc/chap4.html).


could be done separately, but why not now?

dimpase · 2020-02-12T01:47:16Z

@alex-konovalov : this has been fixed already:

bf1c07185c (Max Horn            2020-02-06 18:23:34 +0100 12) documented [here](https://www.gap-system.org/Manuals/pkg/GAPDoc-1.6.2/doc/chap4.html).

cf. https://github.com/dimpase/gap/blob/master/doc/README.md

olexandr-konovalov · 2020-02-12T09:23:34Z

@dimpase sorry was unclear: the suggestion was not to update GAPDoc version number in the URL, but replace by http://www.math.rwth-aachen.de/~Frank.Luebeck/GAPDoc/doc/chap4.html which does not depend on the version number.

https://github.com/dimpase/gap/blob/master/doc/README.md has two hyperlinks for GAPDoc, one to GAP website, one to its Aachen homepage.

dimpase · 2020-02-12T09:48:11Z

done by dimpase@d865442

olexandr-konovalov · 2020-02-12T11:52:43Z

Thanks @dimpase - hope that was last change before merging this.

fingolfin

I just pushed a few more very minor changes, and am happy with the result now. Lets "squash & merge"?

fingolfin · 2020-02-12T17:55:58Z

Also, many thanks to @dimpase for working on this!

Squash and merge PR #3886: - convert Changes manual into a single markdown file - add GAP 4.11 release notes Co-authored by Dima Pasechnik and Max Horn

olexandr-konovalov · 2020-02-12T20:22:18Z

Backported to stable-4.11 in c6e2bac

olexandr-konovalov · 2020-02-16T21:22:15Z

Looking at release wrapping scripts, I see this in make manuals while tut and ref books are built:

#W WARNING: non resolved reference: rec(
  BookName := "hpc",
  Label := "Tasks" )

dimpase added 6 commits February 5, 2020 22:34

convert Changes part of manual into markdown

ce836e2

Merge everything into one file, as well

an attempt to get an anchor

0597e51

removed chap*.md part from anchor names

c131923

added GAP 4.11 notes from wiki

b121dcd

fixed anchors

75c4d7f

fixed some misleading copypastes

13a995a

dimpase requested review from fingolfin and olexandr-konovalov February 6, 2020 01:44

olexandr-konovalov reviewed Feb 6, 2020

View reviewed changes

doc/Changes.md Outdated Show resolved Hide resolved

fixed header dates/version, added self-reference

3b6bf55

fingolfin reviewed Feb 6, 2020

View reviewed changes

doc/README.md Outdated Show resolved Hide resolved

doc/README.md Outdated Show resolved Hide resolved

doc/make_doc.in Show resolved Hide resolved

fingolfin reviewed Feb 6, 2020

View reviewed changes

fingolfin added 5 commits February 6, 2020 18:23

Remove more references to 'changes' manual

bf1c071

changes.md: **GAP** -> GAP

85c261d

Simplify PR links

7bdb420

Drop most of the pointless section numbers

e6ea3a9

Remove useless preamble

5c72952

olexandr-konovalov requested changes Feb 6, 2020

View reviewed changes

dimpase added 2 commits February 6, 2020 22:36

got rid of links to "changes" book in the manual

bc8134f

moved and renamed to CHANGES.md

00e9295

dimpase added 2 commits February 8, 2020 13:00

markdowned most "naked" URLs

7c9125e

fixed the remaining "naked" URLs, removed some TeX's '\'

fe8c470

olexandr-konovalov reviewed Feb 9, 2020

View reviewed changes

CHANGES.md Show resolved Hide resolved

mention HPC-GAP manual at appropriate places

19721d7

olexandr-konovalov requested changes Feb 11, 2020

View reviewed changes

doc/tut/preface.xml Outdated Show resolved Hide resolved

doc/ref/preface.xml Outdated Show resolved Hide resolved

added Labels, corrected wrong bookname

737c467

olexandr-konovalov approved these changes Feb 11, 2020

View reviewed changes

get rid of GAPDoc version

d865442

fingolfin added 2 commits February 12, 2020 18:53

some more reformatting, links

b5ccc4d

hpc

4be5663

fingolfin approved these changes Feb 12, 2020

View reviewed changes

olexandr-konovalov merged commit 4b2185c into gap-system:master Feb 12, 2020

olexandr-konovalov added backport-to-4.11-DONE and removed backport-to-4.11 labels Feb 12, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

convert Changes manuals book into markdown #3886

convert Changes manuals book into markdown #3886

dimpase commented Feb 6, 2020

dimpase commented Feb 6, 2020

olexandr-konovalov commented Feb 6, 2020

fingolfin left a comment

fingolfin Feb 6, 2020

dimpase commented Feb 6, 2020

dimpase commented Feb 6, 2020 •

edited

Loading

olexandr-konovalov left a comment

dimpase commented Feb 6, 2020

dimpase commented Feb 6, 2020

olexandr-konovalov commented Feb 6, 2020

olexandr-konovalov commented Feb 6, 2020

dimpase commented Feb 6, 2020

olexandr-konovalov commented Feb 6, 2020

fingolfin commented Feb 9, 2020

dimpase commented Feb 9, 2020

olexandr-konovalov commented Feb 9, 2020

olexandr-konovalov commented Feb 10, 2020

dimpase commented Feb 10, 2020

olexandr-konovalov commented Feb 10, 2020

dimpase commented Feb 11, 2020

olexandr-konovalov left a comment

olexandr-konovalov Feb 11, 2020

dimpase commented Feb 12, 2020

olexandr-konovalov commented Feb 12, 2020 •

edited by dimpase

Loading

dimpase commented Feb 12, 2020

olexandr-konovalov commented Feb 12, 2020

fingolfin left a comment

fingolfin commented Feb 12, 2020

olexandr-konovalov commented Feb 12, 2020 •

edited

Loading

olexandr-konovalov commented Feb 16, 2020

convert Changes manuals book into markdown #3886

convert Changes manuals book into markdown #3886

Conversation

dimpase commented Feb 6, 2020

Convert Changes manuals book into markdown

Text for release notes

Further details

Checklist for pull request reviewers

dimpase commented Feb 6, 2020

olexandr-konovalov commented Feb 6, 2020

fingolfin left a comment

Choose a reason for hiding this comment

fingolfin Feb 6, 2020

Choose a reason for hiding this comment

dimpase commented Feb 6, 2020

dimpase commented Feb 6, 2020 • edited Loading

olexandr-konovalov left a comment

Choose a reason for hiding this comment

dimpase commented Feb 6, 2020

dimpase commented Feb 6, 2020

olexandr-konovalov commented Feb 6, 2020

olexandr-konovalov commented Feb 6, 2020

dimpase commented Feb 6, 2020

olexandr-konovalov commented Feb 6, 2020

fingolfin commented Feb 9, 2020

dimpase commented Feb 9, 2020

olexandr-konovalov commented Feb 9, 2020

olexandr-konovalov commented Feb 10, 2020

dimpase commented Feb 10, 2020

olexandr-konovalov commented Feb 10, 2020

dimpase commented Feb 11, 2020

olexandr-konovalov left a comment

Choose a reason for hiding this comment

olexandr-konovalov Feb 11, 2020

Choose a reason for hiding this comment

dimpase commented Feb 12, 2020

olexandr-konovalov commented Feb 12, 2020 • edited by dimpase Loading

dimpase commented Feb 12, 2020

olexandr-konovalov commented Feb 12, 2020

fingolfin left a comment

Choose a reason for hiding this comment

fingolfin commented Feb 12, 2020

olexandr-konovalov commented Feb 12, 2020 • edited Loading

olexandr-konovalov commented Feb 16, 2020

dimpase commented Feb 6, 2020 •

edited

Loading

olexandr-konovalov commented Feb 12, 2020 •

edited by dimpase

Loading

olexandr-konovalov commented Feb 12, 2020 •

edited

Loading