Docs: Use asciidoc attributes for upgrade docs to simplify updating

Bug #1487123 reported by Josh Stompro on 2015-08-20
6
This bug affects 1 person
Affects Status Importance Assigned to Milestone
Evergreen
Undecided
Unassigned

Bug Description

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

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) wrote :

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

Remington Steed (rjs7) on 2017-05-12
Changed in evergreen:
status: New → Confirmed
tags: added: pullrequest
Galen Charlton (gmc) wrote :

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) wrote :

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

tags: added: needsdiscussion
removed: pullrequest
To post a comment you must log in.
This report contains Public information  Edit
Everyone can see this information.

Other bug subscribers