Gary Cutler's Programmer's Guide is rapidly approaching three years since its last update. As such, it is missing the new features which have since been added. But, the source to the Programmer's Guide is not public (as far as I know), so we can't update it.
So (for fun) I've been building a set of up-to-date syntax diagrams for GnuCOBOL. The document is a rough draft, missing any explanatory text other than a foreword. I hope people find it useful.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
I have been reading the GFDL (GNU Free Documentation License) from one of the Gary's manuals and, quite frankly, I got more confused than I was before.
In "https://www.gnu.org/licenses/gpl-faq.en.html":
Why don't you use the GPL for manuals?
it says:
It is possible to use the GPL for a manual, but the GNU Free Documentation License (GFDL) is much better for manuals.
The GPL was designed for programs; it contains lots of complex clauses that are crucial for programs, but that would be cumbersome and unnecessary for a book or manual. For instance, anyone publishing the book on paper would have to either include machine-readable “source code” of the book along with each printed copy, or provide a written offer to send the “source code” later.
Meanwhile, the GFDL has clauses that help publishers of free manuals make a profit from selling copies—cover texts, for instance. The special rules for Endorsements sections make it possible to use the GFDL for an official standard. This would permit modified versions, but they could not be labeled as “the standard”.
***Using the GFDL, we permit changes in the text of a manual that covers its technical topic. It is important to be able to change the technical parts, because people who change a program ought to change the documentation to correspond. The freedom to do this is an ethical imperative.
Our manuals also include sections that state our political position about free software. We mark these as “invariant”, so that they cannot be changed or removed. The GFDL makes provisions for these “invariant sections”.
I attached a copy of the GFDL terms included in all documents produced by Gary Cutler.
Meanwhile, I converted these documents (originally in PDF) to MSOffice 2007 ".docx" and OpenDocument ".odt" (with Bookmarks panel), to allow new technical information updates, just in case.
If need be, I'll post them or send them to anyone to do what is best, otherwise, is ok for me as it is (which is FINE).
Can the original source (made by Gary Cutler) be updated in the near future with Edward's work giving a more complete Programmer's Guide Manual of GnuCOBOL 2.n.nnnn adding to it, Edward's credits ? Or, on the other hand, the manual is kept as is until (for fun, or not) someone else make a 2nd addendum to the original plus the 1st addendum ? (and so on...)
The pertinence of this question is based only on the aforementioned paragraph of "Why don't you use the GPL for manuals?", and I quote:
"Using the GFDL, we permit changes in the text of a manual that covers its technical topic. It is important to be able to change the technical parts, because people who change a program ought to change the documentation to correspond. The freedom to do this is an ethical imperative."
Cheers,
MM
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
I'd like to include this in the source tree and ship it with the 2.0 release (may need some tweaks before but it is quite nice already). What do you think about this?
The Changelog you've added is a nice user-view of the changes (you are obviously better than me doing this :-).
I'd like to seperate this from the document, and place an even more simplified version into the manual (including the resulting texi file in gnu-cobol.texi).
Can you go back more - at all this has to cover the changes from GnuCOBOL 1.1 to 2.0? I think Gary has some of the most important changes from 1.1 to 2.x in his Programmer's Guide so it should be able to copy if you don't want to go back further (and the final one-big commit of Roger's 2.0 misses a lot in the commit dialog and Changelogs [If you find something please drop a note and/or add this with question marks in dates in the different Changelog files]).
Thoughts?
Simon
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
I'd like to include this in the source tree and ship it with the 2.0 release (may need some tweaks before but it is quite nice already). What do you think about this?
If you're OK with it being bare-bones, then that's fine with me. If you're going to include the source, be aware that it depends on LaTeX and a lot of packages.
I'd like to seperate [the changelog] from the document, and place an even more simplified version into the manual (including the resulting texi file in gnu-cobol.texi).
Feel free. It's licensed under the FDL (without invariant sections) and converting the code in changelog.tex to texi should be simple.
I should warn you the changelog might be a bit biased towards my changes—it's easier to write about the stuff you know.
Can you go back more - at all this has to cover the changes from GnuCOBOL 1.1 to 2.0?
It goes back to just before the OpenCOBOL CE release, which I think is far enough.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
I for one find your document helpful and it would help a lot if your can :
Add in the missing elements.
Provide updates for the document from one version to the next
(assuming users print it out) as a separate document perhaps as any
page/s that have been changed including new ones as inserted page
numbers (may be in the form of page 14, 14.1, 14.2 etc) so that for any
updates on the changed (or new) pages can be printed and inserted into a
ring binder without having to replace the previous manual/document in
its entirety.
Assuming the tool you are using keeps track of page changes and perhaps
can mark them say with a bar on the outside edge (depending on odd/even
page #). Similar way to MS Word or Libreoffice writer and here you can
ask the program to just print out pages from the changed texts. The
trick here and I do not know how, is to allow new pages to be
incremented by .1 for all inserted new text that creates a new page.
This was the way mainframe manuals were updated saving users from having
to obtain new manuals and just updating an existing one and only
deposing of the replaced pages.
All this assumes users place the loose leaf manuals in to ring binders
which I do for the GC docs.
I do not see the point of online / info text using the man function -
just a pain to read and search through anyway :)
Vincent
On 07/09/16 11:39, Edward Hart wrote:
Here's a slightly updated version with a changelog from 23 November 2013.
This is looking really good Edward. I'm going to brag on LinkedIn on your behalf (and don't worry I'll mention it's a work-in-progress-stay-tuned document).
Nice.
Have good, make well,
Brian
Last edit: Brian Tiffin 2016-10-02
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Thanks so much for doing this. I haven't been able to do much COBOL-wise for the past 3 months as I am busy trying to help my kids with something but your grammar document is really going to help when I can get back to COBOL in January.
-Pat
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
The one file who's name starts with 'GNU-COBOL-2.2-
the next two digits is the sub release version of the manual and this is incremented by one for each update.
This copy is A4 formatted.
All programmers are requested to download it and report all errors and ommisions using the bug reporting tool under the "Programmers Guide" Group.
On providing all please report the problem by specifying manualv revision, manual format (see later but A4 or letter), Chapter number, (page no.) paragraph statement/line number within chapter and the context of the line as printed in manual along with the issue and where appropriate the correction.
As each problem is reported I will :
Update the sources.
Test the sources
Re-Generate a new manual that will increase the 2 digit revision by 1 and update Chapter D specifying all fixes along with the bug number.
Will do this weekly or more often depending on the volume of bugs reported.
Yes I know that the manual is only supplied as A4 but if someone gives the page no., I would like to know what format I am looking at :)
After a few weeks I will also provide a Letter format so all bug reports please also specify the manual format you are using.
Please allow a few days for these fixes as I have to do them on a Mac and transfer the .pdf files/s to my primary system for testing and then uploading to my website.
As the number of updates might be a fair few I would suggest that you do not waste paper by printing it out, at least for the moment.
I will also be working on migrating the manual to LibreOffice odf format as it gets closer to a final status and if I can find out how, will start providing a update service so that only the pages changed or added need to be printed for those of us that use a ring binder to store it. The same way mainframe manual updates are made available.
Saves money, paper and time doing it this way.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Gary Cutler's Programmer's Guide is rapidly approaching three years since its last update. As such, it is missing the new features which have since been added. But, the source to the Programmer's Guide is not public (as far as I know), so we can't update it.
So (for fun) I've been building a set of up-to-date syntax diagrams for GnuCOBOL. The document is a rough draft, missing any explanatory text other than a foreword. I hope people find it useful.
Attached is the PDF and LaTeX source.
I have been reading the GFDL (GNU Free Documentation License) from one of the Gary's manuals and, quite frankly, I got more confused than I was before.
In "https://www.gnu.org/licenses/gpl-faq.en.html":
Why don't you use the GPL for manuals?
it says:
It is possible to use the GPL for a manual, but the GNU Free Documentation License (GFDL) is much better for manuals.
The GPL was designed for programs; it contains lots of complex clauses that are crucial for programs, but that would be cumbersome and unnecessary for a book or manual. For instance, anyone publishing the book on paper would have to either include machine-readable “source code” of the book along with each printed copy, or provide a written offer to send the “source code” later.
Meanwhile, the GFDL has clauses that help publishers of free manuals make a profit from selling copies—cover texts, for instance. The special rules for Endorsements sections make it possible to use the GFDL for an official standard. This would permit modified versions, but they could not be labeled as “the standard”.
***Using the GFDL, we permit changes in the text of a manual that covers its technical topic. It is important to be able to change the technical parts, because people who change a program ought to change the documentation to correspond. The freedom to do this is an ethical imperative.
Our manuals also include sections that state our political position about free software. We mark these as “invariant”, so that they cannot be changed or removed. The GFDL makes provisions for these “invariant sections”.
I attached a copy of the GFDL terms included in all documents produced by Gary Cutler.
Meanwhile, I converted these documents (originally in PDF) to MSOffice 2007 ".docx" and OpenDocument ".odt" (with Bookmarks panel), to allow new technical information updates, just in case.
If need be, I'll post them or send them to anyone to do what is best, otherwise, is ok for me as it is (which is FINE).
Cheers,
MM
Last edit: Mário Matos 2016-09-08
What's your exact question about the GFDL?
Can the original source (made by Gary Cutler) be updated in the near future with Edward's work giving a more complete Programmer's Guide Manual of GnuCOBOL 2.n.nnnn adding to it, Edward's credits ? Or, on the other hand, the manual is kept as is until (for fun, or not) someone else make a 2nd addendum to the original plus the 1st addendum ? (and so on...)
The pertinence of this question is based only on the aforementioned paragraph of "Why don't you use the GPL for manuals?", and I quote:
"Using the GFDL, we permit changes in the text of a manual that covers its technical topic. It is important to be able to change the technical parts, because people who change a program ought to change the documentation to correspond. The freedom to do this is an ethical imperative."
Cheers,
MM
I'll try to contact Gary about creating an updated version for the upcoming release and about the inclusion in the source tree.
It will be nice, thanks.
This is cool. Thanks.
Yes it is, cool. Way cool.
Nice one.
If you have a homebase, drop a note here and I'll add a link to the FAQ, and the Guides page.
Please feel free to snag the bubble generator syntax diagrams and tweak to taste if you feel like it Edward.
http://open-cobol.sourceforge.net/diagrams/all.html
Sources for the data are in the FAQ, public domain, so feel free to cut'n'gut ... or not.
Cheers,
Brian
Here's a slightly updated version with a changelog starting from 23 November 2013.
Last edit: Edward Hart 2016-09-07
Wow, I've missed this the first time.
I'd like to include this in the source tree and ship it with the 2.0 release (may need some tweaks before but it is quite nice already). What do you think about this?
The Changelog you've added is a nice user-view of the changes (you are obviously better than me doing this :-).
I'd like to seperate this from the document, and place an even more simplified version into the manual (including the resulting texi file in gnu-cobol.texi).
Can you go back more - at all this has to cover the changes from GnuCOBOL 1.1 to 2.0? I think Gary has some of the most important changes from 1.1 to 2.x in his Programmer's Guide so it should be able to copy if you don't want to go back further (and the final one-big commit of Roger's 2.0 misses a lot in the commit dialog and Changelogs [If you find something please drop a note and/or add this with question marks in dates in the different Changelog files]).
Thoughts?
Simon
If you're OK with it being bare-bones, then that's fine with me. If you're going to include the source, be aware that it depends on LaTeX and a lot of packages.
Feel free. It's licensed under the FDL (without invariant sections) and converting the code in changelog.tex to texi should be simple.
I should warn you the changelog might be a bit biased towards my changes—it's easier to write about the stuff you know.
It goes back to just before the OpenCOBOL CE release, which I think is far enough.
Edward,
I for one find your document helpful and it would help a lot if your can :
Add in the missing elements.
Provide updates for the document from one version to the next
(assuming users print it out) as a separate document perhaps as any
page/s that have been changed including new ones as inserted page
numbers (may be in the form of page 14, 14.1, 14.2 etc) so that for any
updates on the changed (or new) pages can be printed and inserted into a
ring binder without having to replace the previous manual/document in
its entirety.
Assuming the tool you are using keeps track of page changes and perhaps
can mark them say with a bar on the outside edge (depending on odd/even
page #). Similar way to MS Word or Libreoffice writer and here you can
ask the program to just print out pages from the changed texts. The
trick here and I do not know how, is to allow new pages to be
incremented by .1 for all inserted new text that creates a new page.
This was the way mainframe manuals were updated saving users from having
to obtain new manuals and just updating an existing one and only
deposing of the replaced pages.
All this assumes users place the loose leaf manuals in to ring binders
which I do for the GC docs.
I do not see the point of online / info text using the man function -
just a pain to read and search through anyway :)
Vincent
On 07/09/16 11:39, Edward Hart wrote:
Updated to [r1141], with better-looking syntax diagrams and sections starting on new pages.
This is looking really good Edward. I'm going to brag on LinkedIn on your behalf (and don't worry I'll mention it's a work-in-progress-stay-tuned document).
Nice.
Have good, make well,
Brian
Last edit: Brian Tiffin 2016-10-02
Updated to [r1275].
Hi Edward
Thanks so much for doing this. I haven't been able to do much COBOL-wise for the past 3 months as I am busy trying to help my kids with something but your grammar document is really going to help when I can get back to COBOL in January.
-Pat
Updated to [r1753]. Also includes simple summaries of statements and data division clauses.
I am updating the Gary Cutler Programmers Guide to reflect the soon to be released v2.2 version of Gnu Cobol.
You can find the current release of it at :
http://www.applewood.dtdns.net/files/GnuCobol/
The one file who's name starts with 'GNU-COBOL-2.2-
the next two digits is the sub release version of the manual and this is incremented by one for each update.
This copy is A4 formatted.
All programmers are requested to download it and report all errors and ommisions using the bug reporting tool under the "Programmers Guide" Group.
On providing all please report the problem by specifying manualv revision, manual format (see later but A4 or letter), Chapter number, (page no.) paragraph statement/line number within chapter and the context of the line as printed in manual along with the issue and where appropriate the correction.
As each problem is reported I will :
Will do this weekly or more often depending on the volume of bugs reported.
Yes I know that the manual is only supplied as A4 but if someone gives the page no., I would like to know what format I am looking at :)
After a few weeks I will also provide a Letter format so all bug reports please also specify the manual format you are using.
Please allow a few days for these fixes as I have to do them on a Mac and transfer the .pdf files/s to my primary system for testing and then uploading to my website.
As the number of updates might be a fair few I would suggest that you do not waste paper by printing it out, at least for the moment.
I will also be working on migrating the manual to LibreOffice odf format as it gets closer to a final status and if I can find out how, will start providing a update service so that only the pages changed or added need to be printed for those of us that use a ring binder to store it. The same way mainframe manual updates are made available.
Saves money, paper and time doing it this way.
Sweet.
One thing I'd like to clear up, as it's going to burn people that don't know.
C calling COBOL, page 553, 9.9.5.
That no longer works.
Excuse the loss of indents on the copy'n'paste
Needs to be
Added the CALLING-CONVENTION phrase and EXTERN to the PROCEDURE DIVISION.
Edit: WRONG. That C code does the right thing when it calls cob_init.
The EXTERN is only required when the C code doesn't call cob_init, like for libraries that need callbacks into COBOL,
*I removed a bunch of unhelpful snark from this message that will show up in email form, but not here anymore.
Brian
Last edit: Brian Tiffin 2017-07-15
Hmm, more work to do...
I can't get that example to work as is anymore.
And it's not because of what I was mistakenly all snarky about. That C sample does the proper thing when calling cob_init.
My problems are more localized to gcc not scanning the proper usr/local subdirs.
Foot mouth meet again.
Jeers,
Brian
Found the latest which is actually
GnuCobol/GNU-COBOL-2.2-03JUNE2017-Programmers-Guide-A4.pdf
Ciao Vince ,
in the manual : ACCEPT OMITTED ...is OMITTED (!)
Look at Brian's FAQ for a good documentation.
Updated and both A4 and letter available at :
http://www.applewoodbbs.dtdns.net/files/GnuCobol/
Please help to ensure it is correct by reporting all issues on bug tracker under Programming Guide.
Current list of corrections for 5th edition:
this update list.
reserved).
Last edit: Vincent (Bryan) Coen 2017-07-20
OPTIONS paragraph in the IDENTIFICATION DIVISION is also missing.
see Edward HART grammar.pdf in this thread.