Add the AlanIDE Reference Guide to the repository
thoni56 opened this issue · comments
Robert deFord has written an excellent guide to setup and use the AlanIDE. On my recommendation it was the first documentation to startout as an AsciiDoc.
Robert has kindly stated "it is not copyrighted", but we might need to figure out how to formulate that so that it resonates with the other Alan docs.
- Create subdirectory for it
- Add sources
- Add generated PDF (Maybe? Do we do this? @tajmone
That's great news, I'll write on the list to thank Robert for his kind support!
Copyleft Licenses
Robert has kindly stated "it is not copyrighted", but we might need to figure out how to formulate that so that it resonates with the other Alan docs.
If he has declared it copyleft then we are free to include it in the project with one of the copyleft licenses:
Using any of the above licenses would be both in accordance to Robert's will and compatible with the current Artistic License.
In any case, different licenses can happily coexisist in a project as long as their contents are clearly indicated or isolated into subfolders — probably in the future new documents, tutorials, etc., might get incorporated into the project, and some of them might be differently licensed.
I've encurred many times in similar situations, having found code on forums where the author simply stated that it could be used freely without restrictions, or that he waved any copyright claims on it. Usually a link is more than enough, but if you receieved permission in private communitcation that's even better for you were given such permission personally, and once a work is in public domain there isn't really any further legal stuff to it, actually what we're looking at here has more to do with satisfying the terms of use and conditions of GitHub, since it's a private service and has further requirements when it comes to third party code published by others than its author.
From the above statement, it seems clear tha Robert wishes to waive copyright claims and declarate it into the public domain (although he remains the rightful author forever). Since public domain is not recognized by many countries's laws, it's safer to use one of the three licenses above, since all them are legally valid with the same effects of public domain in most countries in the world (that's the opinion of the legal advisors of various FOSS organizations).
This is a common situation in the IF world actually, were hundreds of adventures have been shared pubblicly (with the author's silent or spoken consent) for years, although not always with a clearly written statement of permission to do so. Since they've been shared on public sites on which their author partook, it's reasonable to deduce consent to it (and this how the IF Archive accepts many old works anyhow).
New Folder for Alan IDE Guide
Shall we name the folder alanide (to keep it short)? Or, anyway, a shortened version of its title (which I currently am not aware of). Will you take care of adding the folder and source file?
I'll more than happily add scripts to convert this guide too, to both PDF and HTML. If the styles permit it, we could reuse the Alan Manual XSL styles for it, if not I'll create a new one. I thought that I would like to keep the Manual's XSL styles in the manual's folder, as that's the main document of reference for the official Alan documentation. Any other document can reuse those styles by including them via relative folders, but if another book/doc needs independet styles it can just add them to its folder.
Of course, I think that it would be good of all Alan related document shared styles and conventions, but on the other hand we can't expect other authors to agree — or, worst, impose it on them, especially if they are freely contributing contents. In any case, the AsciiDoc/DocBook toolchain is very flexible and allows us to handle same source with multiple templates and outputs, so ultimately contents and styles will always be separated.
d3bab5c Added the (almost) original sources from Robert DeFord. Only a few filenames has been cleaned up.
Thanks @thoni56!
The IDE Guide is really cool! I've added a README to the folder, and linked it in the main project page.
Brief Filename, Lowercase No Spaces
I propose that we change the document's filenames to:
ideguide.asciidocideguide.pdf
Because spaces in filenames complicate things with scripts and links (introducing space entities in reference links, etc). I'm for keeping abridged and lowercase names for the documents in this project, and leave it to the deployment scripts to rename them as required when copying them elsewhere (e.g., to the Alan repo).
Build Scripts?
Should I also add to this document the scripts for HTML and PDF conversion?
This would allow to keep the IDE Guide always up to date with the latest templates. Besides, an HTML version of the document would be nice to have too.
Thanks. Agreed. I should have done those changes myself if I had been more adamant when looking through the files, but then again, that's why we have version control ;-) Please, go ahead, on both points.