Giters

alan-if / alan-docs

Alan IF Documentation Project

Home Page:https://git.io/alan-docs

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Broken Links to ALAN IDE and ALAN Beginner's Guides

tajmone opened this issue · comments

commented

Now that we stopped tracking the pre-built HTML and PDF documents in the repository, all links to the following documents are now broken:

We should probably add them to the published branch and update the markdown page to present them and link them.

  • The Alan Beginner's Guide:
    • Add PDF to published branch and update index.md.
    • Update old links to document with new HTML link and new PDF link:
      • ALAN Wiki.
      • ALAN website:
        • Menu: Documentation > BEGINNER'S GUIDE > Beginner's Guide HTML
        • page: Download > Documentation > Beginner's Guide v1.0 (links to old version).
  • Alan IDE Reference Guide:
    • Add PDF and HTML to published branch and update index.md.
    • Update old links to document with new link:
      • ALAN Wiki.
      • ALAN website:
        • Menu: Documentation > ALANIDE > AlanIDE Guide (pdf)
        • page: AlanIDE Intro (direct link to PDF at the very end).

See also the Wiki page for their links and status:

IDE Guide Status

The IDE Guide is already in its final form, and most likely it won't be updated. The PDF is built via the AsciidocFX editor, so there are no build scripts.

Beginner's Guide Status

Although the Beginner's Guide is marked as WIP, the document is production ready (all pending chores relate to providing a downloadable Zip with the polished Lib and tutorial sources). The website should also provide a link to the required source files:

As mentioned, I haven't got to the stage were the build script can also produce an up-to-date Zip archive with all the required code, because I'm still trying to reproduce the various tutorial steps and the associated source files (the tutorial code contains some small bugs that need to be fixed); but eventually we'll be able to provide all assets in a Zip archive.

The HTML doc is being generated as a self-contained file (images are included via DataURIs), so it's safe to just copy the HTML file as is.

There's also a PDF build script, but that was mostly for experimentation, so if we want to also include the PDF version it might be worth checking it first (I didn't really focus on the PDF so far).

commented

If it's OK with you, I'll do the changes myself — after all, I've worked a bit with Jekyll before, and I have successfully cloned the published orphan branch as if it was an independent repository.

To be on the safe side, I'll create a real commit, instead of amending the previous one — in the future, if/when the orphan branch grows too much in history and size, we can always squash together all the past commits, to reduce it.

I would also like to add links to the other documents which are not yet part of the Alan Docs project, like the ALAN Cookbook, which are hosted on the ALAN website. It would make sense to provide external links, for the sake of completion. At some point, the ALAN website should be pointing to the GHPages website for documentation and tutorials, so there will be no need to keep updating links on the website too.

commented

Broken Links of Alan Website

OK @thoni56, I've updated the published branch by adding the missing pre-built documents (Beginner's Guide and AlanIDE Guide) that are no longer tracked on the repository, so end users can download them again. All went smooth, no problems encountered (the only annoying thing is that whenever I fetch I also get the history of the other branches).

I still haven't added a link to the current Alan Cookbook v2 (hosted on Alan website) but I will soon (not a broken link, so no urgency) — although it's not yet part of the Alan Docs project, there's no reason not to provide a link to it (or even host its PDF file on published).

As you can see from the above check-list, there are a number of broken links on the Alan website, still pointing to either the PDF files on the repository (now no longer available) or to the Live HTML Preview service (again, HTML docs no longer tracked in repository).

I've provided you with the new links to both HTML and PDF docs on the GhPages website, and added a task for each broken link (whether in a dropdown menu or web page).

IMO, we should eventually move all ALAN-related documentation to the Alan Docs GHPages website, to avoid having documents scattered all over the Internet, and having to constantly check for broken links, etc.

commented

Very good! Thanks, Tristano. I totally agree with the direction of this, from hosting and pointing to as many documents "as possible".

I've updated the links on the home page.

The Beginner's Guide download on the home page is of course the "historic" version (I've made that clear), but the version of it is 1.0, so TBG in alan-docs should, as it is a better version, have a higher number, it now says 0.2.0. (Version of "conversion" presumably). Maybe even 2.0? Yeah, and I think leaving the PDF of that is quite ok. Actually, I think the PDF:s are getting marginalised now. Unless you want a paper copy to take notes in, I suspect most read what they need online.

This was a good move! Thanks for prompting the idea, and the implementation of it.

(I've left the two top-most check-boxes for you to check, it's a good feeling ;-)

commented

I've updated the links on the home page.

Great!

The Beginner's Guide download on the home page is of course the "historic" version (I've made that clear), but the version of it is 1.0,

Yes, that is indeed worth keeping, for historical reasons. Bear in mind that we're also keeping a copy in the repository of all the original docs that were ported to AsciiDoc (these are tracked, and exempted from ignore rules):

https://github.com/alan-if/alan-docs/tree/master/_assets-src/original-docs

so TBG in alan-docs should, as it is a better version, have a higher number, it now says 0.2.0. (Version of "conversion" presumably). Maybe even 2.0?

The problem here is that I still need to fix some small issues with the Beginner's Guide. If you actually follow the tutorial step by step, starting with the Lib 0.6 as it is, and do all the edits from the instructions, and start to work on the TV Time source, you'll realize that there are some small bugs (mostly punctuation) or omissions in the code shown in the document. So I began fixing the tutorial code of each step, trying to make it work out of the box.

It's a time consuming effort, and the work is not completed. Also, Michael wants to be informed of any significant changes and approve them — so, for anything that is not an obvious typo (a missing ., etc.) I'll have to show him the changes in a dev branch for approval first.

Hence the reason why it's marked as WIP and still in v0.x.x. When I have a whole free day I should just jump into it, replay the whole tutorial from scratch and finish it. So we can finally bump it's version up, and provide the tutorial sources as a downloadable single Zip file.

As for the new version number, I'm not sure whether the port and small fixes work would justify a MAJOR version bump, or if we should just bump the MINOR or PACTH number (v1.1.0 or v1.0.1). If we look at the changes in terms of contents, then it's more of v1.0.1. The document format shouldn't really affect its version number.

Yeah, and I think leaving the PDF of that is quite ok. Actually, I think the PDF:s are getting marginalised now. Unless you want a paper copy to take notes in, I suspect most read what they need online.

I've added it anyway, since the build script was already there and the results are good. I personally don't like PDF at all, especially because you can't enlarge the font as you please, since it's not liquid and re-adaptable text; but also because page breaks in the middle of source code blocks look awful (who needs headers and footers except in printed material?). In terms of accessibility (for the visually impaired), PDF is a horrible format. I think that the only merits of PDF are verbatim printed results, and contents protection.

commented

As for the new version number, I'm not sure whether the port and small fixes work would justify a MAJOR version bump, or if we should just bump the MINOR or PACTH number (v1.1.0 or v1.0.1). If we look at the changes in terms of contents, then it's more of v1.0.1. The document format shouldn't really affect its version number.

I thought that adapting to v3 was one of the "small fixes"? But you are probably right, even that does not merit a major version bump since v3 is the version these days.

commented

I thought that adapting to v3 was one of the "small fixes"?

The final tutorial code actually worked out of the box (with the old library), so there was no need to adapt the code itself, just the code in some of the intermediate steps shown in the document.

commented

Added Alan Cookbook

I've updated the website and added the PDF of the ALAN Cookbook v2 — not just a link, the whole document. So we can start pointing all documentation links to the new website (except for legacy documents which we'll only keep in their new updated version).

Although the Cookbook is a bit outdated, it's already planned to make a new edition in AsciiDoc once the StdLib Manual is done — and I believe that Christian (@dyskos) has already began the porting work. So, in any case, sooner or later we'll be hosting the updated version of the Cookbook.

commented

Yes, I did want to mention that I'm still working on that, though I have been busy with a number of other things lately. I will let y'all know once I've finished so that we can start updating the source material and then making a proper pull request. 🙂