The only major difference I noticed that we use is the fenced code block
format for GFM is different (using the backtick instead of the tilde).
If I missed anything, feel free to reopen the bug and tell me what, or
just submit a patch yourself!
Notably this may cause issues diffing adtpro.sh.txt against the
upstreadm adtpro.sh script. Ours had mixed coding styles, and I figured
having to diff with whitespace ignored was a better solution than
dealing with mixed styles either in the file or in the tree for the
majority of people who aren't likely using the same editor I am.
You can now replace http://appleii.ivanx.com/a2cloud/ for script
downloads just as you can with A2SERVER by setting A2CLOUD_SCRIPT_URL in
your shell's environment. As with A2SERVER, this doesn't affect the
canned files in http://appleii.ivanx.com/a2cloud/files/ because these
aren't really part of the source code. Certainly it makes sense to
mirror these, but GitHub isn't the place to do that.
Adding everything to the tree was a more manual process than it was for
A2SERVER because there are a lot mroe files in Ivan's tree, and they're
not all used anymore. More commits were made in the process, but the
end result is that I don't have to go back and spend a bunch of time
undoing my changes for all the URLs that I shouldn't have changed it in
the first place. Also, it gave me a chance to read through the A2CLOUD
setup script, which was a needed exercise.
Still needed is cleaning up of whitespace to ensure everything is
consistent and adding modelines for vim (and humans who need to know how
to set up editors that aren't vim.) Those can come as batch commits,
and will follow soon.
Note: I've been using kramdown to generate HTML, and kramdown generates
id tags for headings automatically. Redcarpet does not, and in fact
Redcarpet (the official GFM implementation) does not support any
alternative means of specifying id, class, or other HTMLish things. In
other words, redcarpet is extremely limited compared to kramdown.
So just use kramdown right? Well it's not that easy. Kramdown can
parse GFM, but it has some bugs when doing so. For example, when fixing
these last fixmes, I had some level three headings, `### stuff`, which
were rendered as `<p>### stuff</p>` rather than `<h3>stuff</h3>`. Sigh.
When rendering the HTML using kramdown's own syntax variant, it did this
right. But kramdown's variant has some subtle differences in things
like fenced code blocks. GitHub will not render kramdown's fenced code
bocks properly, and kramdown will not render GitHub's fenced code blocks
properly unless set to parse GFM.
In terms of source code, that only matters for README.md, since GitHub
only renders README.md for you. You can't get it to render other .md
files even if you want it to. That said, using two different Markdown
variants causes problems with confusion regarding what is and isn't
valid Markdown syntax. As it is, vim doesn't fully recognize either
syntax using any syntax plugin I've tried. And the precise syntax used
on the GitHub website is obviously going to be GitHub's.
All of this to basically more eloquently say, DAMMIT JOHN GRUBER! He
readily acknowledges the limitations of the reference implementation of
Markdown, suggests anyone who wants to improve the syntax go and do so,
yet stubbornly refuses any effort to standardize these extensions. He's
encouraging a thousand niche forks, but actively trying to sabotage any
standardization. This is a widely acknowledged irritation with the
Markdown family of markup languages.
My notion going forward is that we should assume README.md is in GFM,
and all other .md files are Kramdown format. If I can come up with a
clever way to indicate this syntactic difference, I will.
T. Joseph Carter