New AsciiDoc File Extensions Conventions

[tajmone]

From main README:

File Extensions Conventions

In order to distinguish between AsciiDoc documents according to their role in the project, the following file-extensions conventions are being adopted:

• ".asciidoc" is used for Alan documentation source files.
• ".adoc" is used for project docs (e.g. READMEs) and any AsciiDoc files not intendend for distribution in the Alan documentation.

Using different extensions is also required for automation scripts, which select sourcefiles by their extension during batch operations.

In view of the upcoming adoption of Rake for a unified build toolchain, I would like to amend the above rules to:

ext.	desc.	usage/purpose
.asciidoc	Main source file.	Convert to HTML, PDF, etc.
.adoc	Chapters, Sub-docs, snippets.	include::[] in main source.
.asc .ad	Repo docs (READMEs, etc.).	Devs info, human reading.

This would simplify creating extension-based build rule in Rake.

• @thoni56, would this new convention be OK with you?

Currently, some documents are using the .asciidoc ext. for all files, so I'd like to make their split contents files use .adoc instead.

• Rename sub-docs to .adoc:
  • ALAN Manual
  • Author's Guide

One of such docs is the ALAN Manual, and I'm not sure whether renaming files in master and the rebasing the alpha-dev branch is going to work out or break up everything — of course, I can just try locally and, if thing go wrong, simply reset my branches to their remotes. But having never done this before with branches that apply lots of changes to the files being renamed, I wanted to ask you first, and wondered if you have experience and advise on this.

After renaming the chapter files (changing their extension) in master, and then rebasing the dev branch again, all those files should henceforth be renamed in all the dev branch commits too, since by rebasing we're replaying all those commits on top of the new renaming commit. The big question is whether Git will/can replay/adapt all dev-branch commits operations on those renamed files, instead of re-introducing them with their old names.

The reason I'm asking this is because Git is now always good at detecting renamed files, especially if not renamed explicitly via git mv or if contents are also changed at rename-time, leading Git to interpret the commit as a file deletion and new file addition. This would be disastrous in our case.

Any suggestion, advice, concerns?

[thoni56]

I'm not the one to ask about rebasing. I always seem to be confused and mess up. And I have not done that type of clear re-naming rebase that I recall so I guess just trying it with a single file in a local repo will give some experience.

On the naming issue I have only one comment/question. What's the reason you want to go to .ad for READMEs and that type of files and not keep Markdown which is much easier to display dynamically (like on github, in the Windows explorer, Emacs, ...)?

Otherwise I think separating main files from included files (not intended to be beautified separately) is a good strategy.

[tajmone]

What's the reason you want to go to .ad for READMEs and that type of files and not keep Markdown which is much easier to display dynamically (like on github, in the Windows explorer, Emacs, ...)?

That would be only for special repository pages which share consistent parts of their contents with other ADocs sources (e.g. a dev docs which reuses the ALAN keywords list form the Manual which is CSV file for ADoc table, and similar contents) or the Wiki, which will be mostly developers' reference docs intended for online previewing in order to check details about the project status and some technical details. In some cases, it might be because such docs really need advanced tables features (like row/cell spans, or complexly formatted cells).

These pages are going to be very few in number, but usually involve a good deal of contents which I'd like to avoid having to maintain updated in double-format. Also, these docs (REAMD.ad, DOCS_STATUS.ad, SOME_REF.ad, etc.) are most likely going to be generated by the Asciidoctor coalescer script (soon to become an official backend Gem) because GitHub doesn't support previewing include:: directives, and the latter would also allow me to put all dependencies version info into a single shared file as attributes definition that can be updated in single place and propagated to all such docs.

Even if they are going to be few in number, having a unique (but valid) ADoc extension for them would be better for Rake usage.

So I'm not planning to replace .md docs with ADoc files wholesale, just some of them, where maintenance efforts and DRY benefits justify it. I would also like to keep the README.md file in each folder as short as possible, and move detailed info into other docs and link them.

I know, markdown docs are easier to preview locally, even as raw sources, whereas ADoc sources can quickly become cluttered and less human-friendly to read.

much easier to display dynamically (like on github, in the Windows explorer, Emacs, ...)

GitHub supports AsciiDoc previewing quite well actually, it just doesn't process include:: directives. AsciiDoc previews also automatically generate the TOC, whereas in Markdown I'm using an editor extension to auto-updated it at save time (although GH now also adds its own pop-up navigation bar to MD docs).

There are AsciiDoc previewers for Windows File Explorer.

As for Emacs, I have no idea (I guess there are some ADoc previewer extensions), but probably using pandoc to convert from asciidoctor to html5 would an easy way to create on-the-fly previews with a simple extension via CLI command.

[thoni56]

So I'm not planning to replace .md docs with ADoc files wholesale, just some of them, where maintenance efforts and DRY benefits justify it. I would also like to keep the README.md file in each folder as short as possible, and move detailed info into other docs and link them.

Ok, that's good then.

much easier to display dynamically (like on github, in the Windows explorer, Emacs, ...)

GitHub supports AsciiDoc previewing quite well actually, it just doesn't process include:: directives. AsciiDoc previews also automatically generate the TOC, whereas in Markdown I'm using an editor extension to auto-updated it at save time (although GH now also adds its own pop-up navigation bar to MD docs).

I did know GitHub supports AsciiDoc, and if it also recognizes the .ad extension then that is something.

There are AsciiDoc previewers for Windows File Explorer.

Yes, and some of them are actually working ;-)

There are always work-arounds and tools but that's an extra step. But I was more concerned about the extension, haven't seen .ad as a globally recognized extension for AsciiDoc (like .adoc and .asciidoc).

As for Emacs, I have no idea (I guess there are some ADoc previewer extensions), but probably using pandoc to convert from asciidoctor to html5 would an easy way to create on-the-fly previews with a simple extension via CLI command.

In Emacs there's support for anything ;-) I've used it as my AsciiDoc editor once in a while and it works ok for smaller edits as it semi-renders the AsciiDoc in situ. So if you open an AsciiDoc file Emacs will do that to, at least making the document readable, if not perfect.

If you have to convert the AsciiDoc, then the editor you are using wouldn't matter since we are talking about reading the docs, not writing them. That's a whole other use case.

[tajmone]

I did know GitHub supports AsciiDoc, and if it also recognizes the .ad extension then that is something.

It's hard to say whether alternative extensions have an official status or not, but .ad is used quite a lot in the wild (but even more so just .txt, especially in the Python world). Now I'm not 100% sure where GitHub supports it in rendering (I think so, but I'll do a test).

As it turns out, GitHUb Linguist doesn't, it only associates .asciidoc, .adoc and .asc:

AsciiDoc:
  type: prose
  color: "#73a0c5"
  ace_mode: asciidoc
  wrap: true
  extensions:
  - ".asciidoc"
  - ".adoc"
  - ".asc"
  tm_scope: text.html.asciidoc

so we might want to use .asc instead. (I still think that .ad works, maybe due to language autodetection?)

If you have to convert the AsciiDoc, then the editor you are using wouldn't matter since we are talking about reading the docs, not writing them. That's a whole other use case.

well, not really, since many editors support side-by-side rendering. E.g. AsciidocFX (which is our recommended editor in ALAN Docs) renders the source being edited as HTML in a side panel. VSCode, which can render HTML/CSS in the editor can also offer rich previewing, but unlike AsciidocFX (which is an AsciiDoc editor) it requires a library or tool to convert to HTML. So, if an editor does allow in-editor HTML previewing (e.g. via WebControl panels) then pandoc would be a fast and practical tool to quickly convert on the fly.

It really depends on the editor/IDE and the features it supports. Working with a side-by-side preview of the ADoc source and its HTML rendering it's definitely more practical than having to switch between the editor and the browser.

[tajmone]

Extension .ad Unsupported

I did some tests, and you're right: the .ad extension is not supported by GitHub:

https://github.com/tajmone/testing/blob/master/adoc/test-ad.ad

it will render as plaintext. So we'd have to use .asc instead.

[tajmone]

Renaming Went Well!

Good news @thoni56, changing the extension in the ALAN Manual sub-files from .asciidoc to .adoc went well with rebasing the Alpha branch.

Since Git identifies and tracks files by their SHA1 fingerprint, it doesn't really care about their names. In order words, all changes done in the Alpha Man branch will still refer to the same files, since rebasing will keep continuity of their unique file fingerprints being tracked along the history.

My fear was that I often noticed that when a commit both renames a file and changes its contents a lot, the Git considers the renamed file a new one — but probably this only if you rename the files without using git mv, which I was prudent enough to use this time (although I might have not been necessary either).