I am too old to learn Tcl/Tk, economics, and advanced maths. However, I was a technical writer developing online help and print manuals for telecommunications testing hardware and software (HP), millenium bug patches & insurance policy management (NAB), telecommunications switch controllers including call tapping (Ericsson),antarctic bases building program (AIP), and accounting and bookkeeping software (MYOB). Previous to that I was a publisher and book editor for educational textbooks at Macmillan.
I believe I can assist with the Minsky help files by editing for clarity, spelling, and grammar, and suggesting improvements. I would need access only to the help LaTeX source on Github, but not the Tcl files. I would need to learn LaTeX and have installed TeXmaker, TeXstudio, and LyX on my laptop for comparison. I have used SVN but not Git.
Would someone advise how to begin, please?
Regards,
Hedley
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
It took me about 3 days from zero to having written my first paper
using this book. The book is clearly written, concise and has a dash
of humour, very much a paradigm for computing reference books.
The WYSIWYG tools you mention are probably good, although I can't
personally recommend them. I'm a hard-core CLI guy, and just run
latex/pdflatex on the command line.
As for git, there are some good introductory guides on Github. You
have at least some idea about source code management system with SVN,
git however is a whole other level of beast. The way it works is that
you "fork" a copy of the Minsky repository on Github, then "clone" a
copy of that repository to your local machine. Finally, you checkout
the repository at a particular commit hash (or named branch or tag),
which is your working copy. When you have made your changes, "commit"
your changes to your local repository, then "push" your repository to
your github forked repository, and finally, when you're ready, create
a "pull request". When I get a pull request, I will review the changes
by eye, check that the changed code passes the regression test suite
(called "continuous integration"), possibly request changes, and if
all good, "merge" your pull request into Minsky's master branch. One
of the regression tests checks that the documentation is syntacticly
correct LaTeX. Note that your fork, and the locally cloned copy, are
full copies of the Minsky code repository. It is possible to
completely regenerate the Minsky development environment from these
copies, so the code is safe in the unlikely event that Microsoft
deletes all the github accounts in a pique of anger.
FYI - github is rolling out a change to the name "master branch" to
"main branch", as a measure of sensitivity towards those whose
ancestors suffered under slavery. I don't have a strong feeling one
way or the other over this - my country never engaged in slavery, but
if the "mob" feels this is a good way of going, I have no problem with
that. But for now, Minsky's main branch is still called "master".
Again, for git, I just use the command line, surprise, surprise
:). But I remember my son Hal downloaded github desktop, and was able
to use that effectively (may be Windows only, not sure). Also
Atlassian have a similar product called SourceTree, that my colleagues
at Rapiscan (who are mostly Windows users) use quite extensively.
Translation of LaTeX to HTML takes place using the
LaTeX2HTML tool, which is large perl script. It would probably be
worth while installing that tool as well, to ensure that the HTML
output looks OK in the browser, as that is the primary means people
will read it.
We use the SourceForge tickets system. A few of these are documentation related:
One last thing: Minsky's help system is context sensitive, ie pressing
F1 when hovering the mouse over various items of the interface takes
you to the relevant part fo the manual. There is a perl script which
runs over the HTML files produced by latex2html and generates a TCL
database that makes that all work. Probably a little detailed for you,
but just so you know, there are scattered \ref{} commands in the LaTeX
files that generate the appropriate HTML anchors that make this system
work.
Again - welcome aboard!
Cheers
On Mon, Jul 20, 2020 at 10:49:46AM -0000, Hedley Finger wrote:
I am too old to learn Tcl/Tk, economics, and advanced maths. However, I was a
technical writer developing online help and print manuals for
telecommunications testing hardware and software (HP), millenium bug patches &
insurance policy management (NAB), telecommunications switch controllers
including call tapping (Ericsson),antarctic bases building program (AIP), and
accounting and bookkeeping software (MYOB). Previous to that I was a publisher
and book editor for educational textbooks at Macmillan.
I believe I can assist with the Minsky help files by editing for clarity,
spelling, and grammar, and suggesting improvements. I would need access only to
the help LaTeX source on Github, but not the Tcl files. I would need to learn
LaTeX and have installed TeXmaker, TeXstudio, and LyX on my laptop for
comparison. I have used SVN but not Git.
Ubuntu 18.04.4 LTS Bionic Beaver
Minsky 2.19.0.beta.17
I am too old to learn Tcl/Tk, economics, and advanced maths. However, I was a technical writer developing online help and print manuals for telecommunications testing hardware and software (HP), millenium bug patches & insurance policy management (NAB), telecommunications switch controllers including call tapping (Ericsson),antarctic bases building program (AIP), and accounting and bookkeeping software (MYOB). Previous to that I was a publisher and book editor for educational textbooks at Macmillan.
I believe I can assist with the Minsky help files by editing for clarity, spelling, and grammar, and suggesting improvements. I would need access only to the help LaTeX source on Github, but not the Tcl files. I would need to learn LaTeX and have installed TeXmaker, TeXstudio, and LyX on my laptop for comparison. I have used SVN but not Git.
Would someone advise how to begin, please?
Regards,
Hedley
Thanks Hedley, that would be most welcome.
As for learning LaTeX, I can thoroughly recommend Leslie Lamport's book https://www.amazon.com.au/Latex-Document-Preparation-System-Reference/dp/0201529831
It took me about 3 days from zero to having written my first paper
using this book. The book is clearly written, concise and has a dash
of humour, very much a paradigm for computing reference books.
The WYSIWYG tools you mention are probably good, although I can't
personally recommend them. I'm a hard-core CLI guy, and just run
latex/pdflatex on the command line.
As for git, there are some good introductory guides on Github. You
have at least some idea about source code management system with SVN,
git however is a whole other level of beast. The way it works is that
you "fork" a copy of the Minsky repository on Github, then "clone" a
copy of that repository to your local machine. Finally, you checkout
the repository at a particular commit hash (or named branch or tag),
which is your working copy. When you have made your changes, "commit"
your changes to your local repository, then "push" your repository to
your github forked repository, and finally, when you're ready, create
a "pull request". When I get a pull request, I will review the changes
by eye, check that the changed code passes the regression test suite
(called "continuous integration"), possibly request changes, and if
all good, "merge" your pull request into Minsky's master branch. One
of the regression tests checks that the documentation is syntacticly
correct LaTeX. Note that your fork, and the locally cloned copy, are
full copies of the Minsky code repository. It is possible to
completely regenerate the Minsky development environment from these
copies, so the code is safe in the unlikely event that Microsoft
deletes all the github accounts in a pique of anger.
FYI - github is rolling out a change to the name "master branch" to
"main branch", as a measure of sensitivity towards those whose
ancestors suffered under slavery. I don't have a strong feeling one
way or the other over this - my country never engaged in slavery, but
if the "mob" feels this is a good way of going, I have no problem with
that. But for now, Minsky's main branch is still called "master".
Again, for git, I just use the command line, surprise, surprise
:). But I remember my son Hal downloaded github desktop, and was able
to use that effectively (may be Windows only, not sure). Also
Atlassian have a similar product called SourceTree, that my colleagues
at Rapiscan (who are mostly Windows users) use quite extensively.
Translation of LaTeX to HTML takes place using the
LaTeX2HTML tool, which is large perl script. It would probably be
worth while installing that tool as well, to ensure that the HTML
output looks OK in the browser, as that is the primary means people
will read it.
We use the SourceForge tickets system. A few of these are documentation related:
https://sourceforge.net/p/minsky/tickets/1069/
https://sourceforge.net/p/minsky/tickets/768/
One last thing: Minsky's help system is context sensitive, ie pressing
F1 when hovering the mouse over various items of the interface takes
you to the relevant part fo the manual. There is a perl script which
runs over the HTML files produced by latex2html and generates a TCL
database that makes that all work. Probably a little detailed for you,
but just so you know, there are scattered \ref{} commands in the LaTeX
files that generate the appropriate HTML anchors that make this system
work.
Again - welcome aboard!
Cheers
On Mon, Jul 20, 2020 at 10:49:46AM -0000, Hedley Finger wrote:
--
Dr Russell Standish Phone 0425 253119 (mobile)
Principal, High Performance Coders hpcoder@hpcoders.com.au
http://www.hpcoders.com.au