Docs: Use asciidoc attributes for upgrade docs to simplify updating

[Josh Stompro]

Asciidoc has the ability to setup attributes that can be used as variables in the docs. I've been toying with the idea of using them to make it easier for the upgrading docs to be updated between versions, and possibly the install docs also.

Docs for document attributes
http://www.methods.co.nz/asciidoc/userguide.html#_document_attributes

And a gotcha about attributes in listing blocks is documented at
http://mrhaki.blogspot.com/2014/05/awesome-asciidoc-substitute-attribute.html

One of the issue with this is that it makes the plain text source of the asciidoc less readable for those that may open it with the text editor. I personally use the web version of the docs, so this doesn't bother me. But maybe that is a deal breaker for others.

This make make auto-editing the file easier, since you wouldn't need to worry about search and replace issues with the sql upgrade script names.

Josh

[Josh Stompro (u-launchpad-stompro-org)]

user/stompro/lp1487123_upgrade_docs_attributes

http://git.evergreen-ils.org/?p=working/Evergreen.git;a=shortlog;h=refs/heads/user/stompro/lp1487123_upgrade_docs_attributes

Here is a branch that sets up attributes for the version numbers that change between versions. I think the sql scripts will still need to be adjusted.. Hopefully an automatic DB upgrade process will take over sometime so we don't have to list those out as examples. Maybe there already is one?

Josh

[Remington Steed (rjs7)]

I rebased Josh's branch and resolved a few conflicts. I also added a commit that simplifies the examples of applying DB upgrade scripts.

http://git.evergreen-ils.org/?p=working/Evergreen.git;a=shortlog;h=refs/heads/user/rsteed/lp1487123_asciidoc_version_attribs

[Galen Charlton (gmc)]

I have a quibble with Remington's suggested follow-up: while I'm not opposed to the idea of not explicitly mentioning every version-upgrade script, I think it shouldn't stop short, lest somebody in a hurry wonders why things stop at 2.6.0. In other words, the last script mentioned should be the current version.

Automating that section is probably beyond what AsciiDoc attributes can do, but it wouldn't be hard to have build/tools/make_release generate a commit that handles it, removing a manual step from the release-building process.

Regarding a point that Josh made, I do think it would be very handy to continue to allow installers and upgraders to be able to copy/paste from plain text versions of the instructions contained in the tarballs. One way to do this might be to generate plain text output from the AsciiDoc, e.g., by doing something like this:

a2x -L -f text docs/installation/server_upgrade.adoc
cp docs/installation/server_upgrade.text UPGRADE

Note that I needed -L because server_upgrade.adoc contains section references to other parts of the manual; I also needed to install w3m.

[Andrea Neiman (aneiman)]

Noting that this may need further review after the Antora move; given that, I'm removing the pullrequest and adding needsdiscussion.