[oi-dev] Updated OpenIndiana FAQ (3rd draft)
makruger2000 at gmail.com
Mon Feb 15 04:46:01 UTC 2016
On 02/10/2016 06:14 AM, Alexander Pyhalov wrote:
> Hi. I have several notices.
> "Some notable features of OpenSolaris were the introduction of the all
> familiar GNOME desktop, GNU userland tools, and a new network based
> package manager (IPS)"
> It seems comma before "and" is not necessary, but I'm not a native speaker.
> In Feature/Description table some descriptions could be a bit expanded.
> For non-Solaris user descriptions "Service Management Facility" and
> "Fault Management Architecture" say nothing. At least there should be
> links to documentation, wiki or wikipedia.
> I'd avoid speaking about 32-bit support. It seems we are going to nuke
> it in future, and in immediate future more and more 64-bit-only
> applications will appear. One old good example is qemu-kvm.
> Adam, can we host
> http://www.linuxtopia.org/online_books/opensolaris_2008/index.html on OI
> infrastructure? Referencing to linuxtopia site seems strange.
> "Utilities maintenance - pkg". Link seems to be broken. I think this
> item needs brief clarification.
> "As illumos is not itself a distribution, OpenIndiana combines
> illumos-gate with OpenIndiana derived oi-userland"
> I think something is wrong with this sentence.
> "At this time, the following distributions are known to support the
> SPARC platform:.."
> I think it would be good to reorganize the list in alphabetic order.
I've applied all the edits you suggested and tossed an updated copy out
on Github Gist: https://gist.github.com/makruger/83209277d6382c01c534
The creole markup rendering is not quite perfect (a few extra ** here
and there), but github has rendered it mostly correct.
As for hosting the 2009.06 docs, I suppose we could do it on
openindiana.org, but will we (those working on the docs) be able to
easily update them there?
e.g. will we be able to obtain FTP access to an upload directory so the
content can be updated as the documentation project progresses along? If
not, then perhaps hosting the docs on github pages might provide better
access to the doc team.
Ideally what I'd really like to see happen is the conversion of the
solbook xml to asciidoc and import all the OpenSolaris books into github
in that particular text markup format. I'd like to do the same with the
handbook, FAQ, and anything else I am working on as well.
Solbook and docbook aren't much fun to work with, whereas ascidoc is
plainly readable. And using the ruby acscidoctor toolkit, it produces
some very nice HTML5 output, as well as PDF and EPUBS too.
After playing around a bit with both python based Sphinx and ruby based
Ascidoctor, I think the later is the way to go. Ascidoctor installs fine
on Hipster as a ruby gem (yes even with our ancient ruby 1.9).
If the proposed github doc repo could be configured with a commit hook
to convert the docs and push them to github pages, then we'd have a
fully automated (and might I also say very modern) documentation
toolchain. This would really lower the bar for those working on the docs
and mean less fuss for everyone involved. One would just need to
understand how to use GIT and how to write docs in ASCIIDOC using the
text editor of their choice.
More information about the oi-dev