search

asciidoctor / asciidoctor.org

:globe_with_meridians: Asciidoctor project site. Composed in AsciiDoc. Baked with Awestruct.
https://asciidoctor.org
Other
322 stars 807 forks source link

Document options for offline installation #577

Open rockyallen opened 8 years ago

rockyallen commented 8 years ago

re http://discuss.asciidoctor.org/Offline-installation-tt4534.html#a4536

"Technically, everything can be installed offline, provided you have the necessary packages. Of course, will need to validate that statement. (As you know, there are numerous attributes that need to be set in order for the generated HTML document to work offline, but that's a separate topic.)

Asciidoctor (core):: If you download the gem from https://rubygems.org/downloads/asciidoctor-1.5.4.gem (linked from https://rubygems.org/gems/asciidoctor), you can install it using the gem install command without an internet connection. You'd need to do the same for any additional gem you need.

If you're on a Linux box, you can download the Linux package (rpm, deb, apk) and install that offline instead.

fopub:: Once you run fopub once, it should operate offline after that. The initial run uses Gradle to collect all the dependencies and setup the installation structure.

(If we put in a little bit of work, we could create a distribution for fopub that has the files already downloaded and in place).

Asciidoctor Diagram:: This is more complex since it requires not only the gem to be installed, but also any binary that is used (such as dot). Again, download the gem from https://rubygems.org/downloads/asciidoctor-diagram-1.4.0.gem (linked from https://rubygems.org/gems/asciidoctor-diagram) and install it using the gem install command.

The chart extension really isn't packaged at this point, so I don't really have instructions for that one. Eventually, we'll want something like an asciidoctor-chart gem.

-Dan"

It should cover Windows and and Linux, and Ruby and Ant, Maven and Gradle. The instructions for the extensions should be with the extensions, but the main manual should have a statement of what is possible and links to the details.

rockyallen commented 7 years ago

Results of experiments so far:

https://github.com/rockyallen/asciidoctoressays/blob/master/portableasciidoctor/offlineinstall.pdf

I use the standalone one at work so I know it works. Yet to demonstrate it from USB. It doesn't seem quite right for the user guide - any (polite) suggestions where to put it?

mojavelinux commented 7 years ago

I think a dedicated document under the /docs/ folder makes the most sense.

Shouldn't we also consider whether the generated document requires the internet and how to deal with that? (for instance, we can't use Google Fonts or Font Awesome offline). There are some attributes to control this behavior, but we may need more (or document the gaps).

rockyallen commented 7 years ago

Offline viewing is #578-a pr is coming!

rockyallen commented 7 years ago

Changed my mind about the offline building document-rather than writing about it, I will create a standalone asciidoctor-portable project, and post it if it works.

mojavelinux commented 7 years ago

Sometimes, the best way to explain is just to show it. I can't wait to see it.