feature request: offline documentation
Hi,
I noticed that the help-menu in OpenSCAD (e.g. the cheatsheet and the
linked syntax-descriptions) always opens a website. So, without an
active internet-connection, it's not possible to look at the cheatsheet
or to look up some syntax.
I would suggest to include the documentation (at least the cheatsheet
and all linked pages) into the OpenSCAD-downloads, and then open these
local files from the help-menu, so that help works without internet.
The currently simplest way to achieve this would probably be to include
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Print_version
(incl. all images) and to include a modified cheatsheet which links
to the appropriate sections of this page.
best regards
Roland
On 07/04/2015 09:36 AM, Roland Koebler wrote:
I noticed that the help-menu in OpenSCAD (e.g. the cheatsheet and the
linked syntax-descriptions) always opens a website. So, without an
active internet-connection, it's not possible to look at the cheatsheet
or to look up some syntax.
I agree, that would be nice to have.
The currently simplest way to achieve this would probably be to include
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Print_version
(incl. all images) and to include a modified cheatsheet which links
to the appropriate sections of this page.
Including the cheat-sheet should be relatively easy. That Print_version
of the manual looks hopelessly out of date though, so unless someone
finds the time to update it, it's probably not helpful to include that.
Also I'm not fond of having multiple places to update when something in
the manual changes (yes, the print version is basically just links to
the other articles, but still it violates the "dont-repeat-yourself"
principle which is usually a good thing, not only for code but also
for documentation).
I'm meaning to look at the Wikipedia export feature to maybe find a
way to automatically export the manual and create an offline version
(ideally in different formats like PDF and epub) from that, but so
far I'm not having time for that.
ciao,
Torsten.
Well, I don't have "LOTS" of time, but I probably have more than most. I am
a retired programmer, and very interested in OpenSCAD.
I also, don't know what this entails.
But, can I help?
Jerry
Jerry
--
Extra Ham Operator: K7AZJ
Registered Linux User: 275424
Raspberry Pi and Arduino developer
The most exciting phrase to hear in science - the one that heralds new
discoveries - is not "Eureka!" but "That's funny...".- Isaac. Asimov
I
*f you give someone a program, you will frustrate them for a day; if you
teach them how to program, you will frustrate them for a lifetime. *-
Anonymous
If writing good code requires very little comments, then writing really
excellent code requires no comments at all!- Ken Thompson
On Sat, Jul 4, 2015 at 7:53 AM, Torsten Paul Torsten.Paul@gmx.de wrote:
On 07/04/2015 09:36 AM, Roland Koebler wrote:
I noticed that the help-menu in OpenSCAD (e.g. the cheatsheet and the
linked syntax-descriptions) always opens a website. So, without an
active internet-connection, it's not possible to look at the cheatsheet
or to look up some syntax.
I agree, that would be nice to have.
The currently simplest way to achieve this would probably be to include
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Print_version
(incl. all images) and to include a modified cheatsheet which links
to the appropriate sections of this page.
Including the cheat-sheet should be relatively easy. That Print_version
of the manual looks hopelessly out of date though, so unless someone
finds the time to update it, it's probably not helpful to include that.
Also I'm not fond of having multiple places to update when something in
the manual changes (yes, the print version is basically just links to
the other articles, but still it violates the "dont-repeat-yourself"
principle which is usually a good thing, not only for code but also
for documentation).
I'm meaning to look at the Wikipedia export feature to maybe find a
way to automatically export the manual and create an offline version
(ideally in different formats like PDF and epub) from that, but so
far I'm not having time for that.
ciao,
Torsten.
OpenSCAD mailing list
Discuss@lists.openscad.org
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
On 07/04/2015 03:15 PM, Jerry Davis wrote:
Well, I don't have "LOTS" of time, but I probably have more than most. I am
a retired programmer, and very interested in OpenSCAD.
Cool. There's no manager standing around waving deadlines before
our noses :-).
I also, don't know what this entails.
I only looked at what's possible in general, so there's probably
quite some investigation of details needed. But in my mind, that's
also part of the fun when working on new stuff.
Wikipedia allows the export of data via a simple interface
https://en.wikipedia.org/wiki/Help:Export
I guess this is basically intended to be the source for backups
and/or for transferring data from one installation to another.
There's big list of converters around, but I have no idea how
usable those are. Most seem to target the import into another wiki
software but some will convert to other file formats already.
https://www.mediawiki.org/wiki/Alternative_parsers
For example it lists WikiPDF by Felipe Sanches who's even on the
list here, I think :-).
The manual export is easy, just go to
https://en.wikibooks.org/wiki/Special:Export
and enter "OpenSCAD_User_Manual" into the "Add pages from category".
This exports all the text content into one big XML file.
I think the ideal option would be an automated way to convert this
XML file into different formats. As first step, to make it usable
as off-line documentation, the target would probably be either
static HTML that could be shipped with OpenSCAD or maybe PDF.
I'm not sure if that needs actual programming to be done, or if
the existing tools are maybe already sufficient for that. So the
task could be one of
-
write a script that does all the conversion and image downloading
-
write a simple script to just run various existing tools
-
go though the wiki pages of the manual and adjust some of the
text so it works nicely with some existing tool -
something else I did not yet think of...
Ideally that should run on Linux so it could be integrated into
one of the automatic build servers (e.g. Travis). But I guess
a manual solution that is just started now an then would also
be a nice thing.
ciao,
Torsten.
I am thinking the ideal solution would be to have one source (html), that
can be used for both online and offline documentation. And if the html
"shipped" with the application, then the help from the application (would
default to the offline version).
Jerry
--
Extra Ham Operator: K7AZJ
Registered Linux User: 275424
Raspberry Pi and Arduino developer
The most exciting phrase to hear in science - the one that heralds new
discoveries - is not "Eureka!" but "That's funny...".- Isaac. Asimov
I
*f you give someone a program, you will frustrate them for a day; if you
teach them how to program, you will frustrate them for a lifetime. *-
Anonymous
If writing good code requires very little comments, then writing really
excellent code requires no comments at all!- Ken Thompson
On Sat, Jul 4, 2015 at 9:05 AM, Torsten Paul Torsten.Paul@gmx.de wrote:
On 07/04/2015 03:15 PM, Jerry Davis wrote:
Well, I don't have "LOTS" of time, but I probably have more than most. I
am
a retired programmer, and very interested in OpenSCAD.
Cool. There's no manager standing around waving deadlines before
our noses :-).
I also, don't know what this entails.
I only looked at what's possible in general, so there's probably
quite some investigation of details needed. But in my mind, that's
also part of the fun when working on new stuff.
Wikipedia allows the export of data via a simple interface
https://en.wikipedia.org/wiki/Help:Export
I guess this is basically intended to be the source for backups
and/or for transferring data from one installation to another.
There's big list of converters around, but I have no idea how
usable those are. Most seem to target the import into another wiki
software but some will convert to other file formats already.
https://www.mediawiki.org/wiki/Alternative_parsers
For example it lists WikiPDF by Felipe Sanches who's even on the
list here, I think :-).
The manual export is easy, just go to
https://en.wikibooks.org/wiki/Special:Export
and enter "OpenSCAD_User_Manual" into the "Add pages from category".
This exports all the text content into one big XML file.
I think the ideal option would be an automated way to convert this
XML file into different formats. As first step, to make it usable
as off-line documentation, the target would probably be either
static HTML that could be shipped with OpenSCAD or maybe PDF.
I'm not sure if that needs actual programming to be done, or if
the existing tools are maybe already sufficient for that. So the
task could be one of
-
write a script that does all the conversion and image downloading
-
write a simple script to just run various existing tools
-
go though the wiki pages of the manual and adjust some of the
text so it works nicely with some existing tool -
something else I did not yet think of...
Ideally that should run on Linux so it could be integrated into
one of the automatic build servers (e.g. Travis). But I guess
a manual solution that is just started now an then would also
be a nice thing.
ciao,
Torsten.
OpenSCAD mailing list
Discuss@lists.openscad.org
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
On 07/05/2015 10:10 PM, Jerry Davis wrote:
I am thinking the ideal solution would be to have one source (html), that
can be used for both online and offline documentation. And if the html
"shipped" with the application, then the help from the application (would
default to the offline version).
Right, that's another option. It has one big drawback though. As the
current manual is a Wiki, it's very easy to contribute to the documentation.
Having it on github or so might create an additional barrier to just fix
something or include additional info in the documentation.
I'm not sure which way is going to be better in the long run, but I do
fear losing contributions by people who don't want to bother with github.
ciao,
Torsten.
You don't need to move the manual to github.
I just tried this using Google Chrome: navigate to
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual, then "Save as complete
web page". This created OpenSCAD.html and an OpenSCAD directory, containing
the complete user manual in HTML. I can open OpenSCAD.html from my local
hard drive using a web browser, and I get the user manual.
If we can find a tool that does this from the command line, then we can add
this command to the build process.
On 5 July 2015 at 16:35, Torsten Paul Torsten.Paul@gmx.de wrote:
On 07/05/2015 10:10 PM, Jerry Davis wrote:
I am thinking the ideal solution would be to have one source (html), that
can be used for both online and offline documentation. And if the html
"shipped" with the application, then the help from the application (would
default to the offline version).
Right, that's another option. It has one big drawback though. As the
current manual is a Wiki, it's very easy to contribute to the
documentation.
Having it on github or so might create an additional barrier to just fix
something or include additional info in the documentation.
I'm not sure which way is going to be better in the long run, but I do
fear losing contributions by people who don't want to bother with github.
ciao,
Torsten.
OpenSCAD mailing list
Discuss@lists.openscad.org
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
@doug Me thinks you meant:
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Print_version
2015-07-06 0:10 GMT+02:00 doug moen doug@moens.org:
You don't need to move the manual to github.
I just tried this using Google Chrome: navigate to
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual, then "Save as
complete web page". This created OpenSCAD.html and an OpenSCAD directory,
containing the complete user manual in HTML. I can open OpenSCAD.html from
my local hard drive using a web browser, and I get the user manual.
If we can find a tool that does this from the command line, then we can
add this command to the build process.
On 5 July 2015 at 16:35, Torsten Paul Torsten.Paul@gmx.de wrote:
On 07/05/2015 10:10 PM, Jerry Davis wrote:
I am thinking the ideal solution would be to have one source (html), that
can be used for both online and offline documentation. And if the html
"shipped" with the application, then the help from the application (would
default to the offline version).
Right, that's another option. It has one big drawback though. As the
current manual is a Wiki, it's very easy to contribute to the
documentation.
Having it on github or so might create an additional barrier to just fix
something or include additional info in the documentation.
I'm not sure which way is going to be better in the long run, but I do
fear losing contributions by people who don't want to bother with github.
ciao,
Torsten.
OpenSCAD mailing list
Discuss@lists.openscad.org
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
--
stempeldergeschichte@googlemail.com karsten@rohrbach.de
P.S. Falls meine E-Mail kürzer ausfällt als Dir angenehm ist:
Ich probiere gerade aus kurze Antworten statt gar keine Antworten zu
schreiben.
Wenn Du gerne mehr lesen möchtest, dann lass es mich bitte wissen.
P.S. In case my e-mail is shorter than you enjoy:
I am currently trying short replies instead of no replies at all.
Please let me know, if you like to read more.
Enjoy!
I used to print this to a pdf-printer and used it offline for the longest
time.
2015-07-06 0:21 GMT+02:00 Peter Falke stempeldergeschichte@googlemail.com:
@doug Me thinks you meant:
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Print_version
2015-07-06 0:10 GMT+02:00 doug moen doug@moens.org:
You don't need to move the manual to github.
I just tried this using Google Chrome: navigate to
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual, then "Save as
complete web page". This created OpenSCAD.html and an OpenSCAD directory,
containing the complete user manual in HTML. I can open OpenSCAD.html from
my local hard drive using a web browser, and I get the user manual.
If we can find a tool that does this from the command line, then we can
add this command to the build process.
On 5 July 2015 at 16:35, Torsten Paul Torsten.Paul@gmx.de wrote:
On 07/05/2015 10:10 PM, Jerry Davis wrote:
I am thinking the ideal solution would be to have one source (html),
that
can be used for both online and offline documentation. And if the html
"shipped" with the application, then the help from the application
(would
default to the offline version).
Right, that's another option. It has one big drawback though. As the
current manual is a Wiki, it's very easy to contribute to the
documentation.
Having it on github or so might create an additional barrier to just fix
something or include additional info in the documentation.
I'm not sure which way is going to be better in the long run, but I do
fear losing contributions by people who don't want to bother with github.
ciao,
Torsten.
OpenSCAD mailing list
Discuss@lists.openscad.org
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
--
stempeldergeschichte@googlemail.com karsten@rohrbach.de
P.S. Falls meine E-Mail kürzer ausfällt als Dir angenehm ist:
Ich probiere gerade aus kurze Antworten statt gar keine Antworten zu
schreiben.
Wenn Du gerne mehr lesen möchtest, dann lass es mich bitte wissen.
P.S. In case my e-mail is shorter than you enjoy:
I am currently trying short replies instead of no replies at all.
Please let me know, if you like to read more.
Enjoy!
--
stempeldergeschichte@googlemail.com karsten@rohrbach.de
P.S. Falls meine E-Mail kürzer ausfällt als Dir angenehm ist:
Ich probiere gerade aus kurze Antworten statt gar keine Antworten zu
schreiben.
Wenn Du gerne mehr lesen möchtest, dann lass es mich bitte wissen.
P.S. In case my e-mail is shorter than you enjoy:
I am currently trying short replies instead of no replies at all.
Please let me know, if you like to read more.
Enjoy!
Actually U need to look at the preview on that page and print that.
2015-07-06 0:23 GMT+02:00 Peter Falke stempeldergeschichte@googlemail.com:
I used to print this to a pdf-printer and used it offline for the longest
time.
2015-07-06 0:21 GMT+02:00 Peter Falke <stempeldergeschichte@googlemail.com
:
@doug Me thinks you meant:
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Print_version
2015-07-06 0:10 GMT+02:00 doug moen doug@moens.org:
You don't need to move the manual to github.
I just tried this using Google Chrome: navigate to
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual, then "Save as
complete web page". This created OpenSCAD.html and an OpenSCAD directory,
containing the complete user manual in HTML. I can open OpenSCAD.html from
my local hard drive using a web browser, and I get the user manual.
If we can find a tool that does this from the command line, then we can
add this command to the build process.
On 5 July 2015 at 16:35, Torsten Paul Torsten.Paul@gmx.de wrote:
On 07/05/2015 10:10 PM, Jerry Davis wrote:
I am thinking the ideal solution would be to have one source (html),
that
can be used for both online and offline documentation. And if the html
"shipped" with the application, then the help from the application
(would
default to the offline version).
Right, that's another option. It has one big drawback though. As the
current manual is a Wiki, it's very easy to contribute to the
documentation.
Having it on github or so might create an additional barrier to just fix
something or include additional info in the documentation.
I'm not sure which way is going to be better in the long run, but I do
fear losing contributions by people who don't want to bother with
github.
ciao,
Torsten.
OpenSCAD mailing list
Discuss@lists.openscad.org
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
--
stempeldergeschichte@googlemail.com karsten@rohrbach.de
P.S. Falls meine E-Mail kürzer ausfällt als Dir angenehm ist:
Ich probiere gerade aus kurze Antworten statt gar keine Antworten zu
schreiben.
Wenn Du gerne mehr lesen möchtest, dann lass es mich bitte wissen.
P.S. In case my e-mail is shorter than you enjoy:
I am currently trying short replies instead of no replies at all.
Please let me know, if you like to read more.
Enjoy!
--
stempeldergeschichte@googlemail.com karsten@rohrbach.de
P.S. Falls meine E-Mail kürzer ausfällt als Dir angenehm ist:
Ich probiere gerade aus kurze Antworten statt gar keine Antworten zu
schreiben.
Wenn Du gerne mehr lesen möchtest, dann lass es mich bitte wissen.
P.S. In case my e-mail is shorter than you enjoy:
I am currently trying short replies instead of no replies at all.
Please let me know, if you like to read more.
Enjoy!
--
stempeldergeschichte@googlemail.com karsten@rohrbach.de
P.S. Falls meine E-Mail kürzer ausfällt als Dir angenehm ist:
Ich probiere gerade aus kurze Antworten statt gar keine Antworten zu
schreiben.
Wenn Du gerne mehr lesen möchtest, dann lass es mich bitte wissen.
P.S. In case my e-mail is shorter than you enjoy:
I am currently trying short replies instead of no replies at all.
Please let me know, if you like to read more.
Enjoy!