You are here

8 OpenSolaris Docs Refresh Project

Primary tabs

OpenSolaris redistributable docs

  • The source for PDL licensed restributable docs is Solbook XML 3.5 (and in some cases Solbook XML 3.6). Solbook is a simplified subset of Docbook. We have a conversion tool which can handle Solbook XML 3.5, but we do not have DTD's for any other version. Assuming the differences between these versions are not too great, we might be able to trick the java conversion tool by simply changing the version number within the DTD (don't know if that will work, haven't tried it yet).
  • As a way forward, we should consider either converting them all to Docbook 5, or some kind of text markup (e.g. restructured text, etc.).
  • For books for which we do not have the source, perhaps pandoc can be used to reconvert the HTML back to docbook 5, text markup, etc.
    • Using a text based markup would lower the bar to working on the docs.
      • The PC-BSD Project follows this approach using the python based Sphinx toolchain (which is based on restructured text).
    • For comparison's sake, the FreeBSD project uses Docbook 5, which they maintain using plain old text editors (VIM, gedit, nano, etc.).
      • The FreeBSD project then uses an semi-automated XML toolchain to validate and convert the source code to other formats.
      • The FreeBSD project hosts their Docbook 5 XML source in a single subversion repository where you check out the entire project.
      • For more details of the FreeBSD docs process, see: https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/index.html
  • Whatever documentation build system we end up using....it should be natively supported on OI (and ideally cross platform as well).


OpenSolaris Doc Refresh Challenges

  • The books all reference each other using the original SUN URL's.
    • Even the illumos books have broken sun links (thus also need some love).
  • The books have difficult to decipher names.
  • The books are not really mobile friendly (single page HTML with embedded navigation is more friendly - see FreeBSD Handbook)
  • Soldoc to html conversion tool chain is broken (Indexing does not work).
  • XML is hard to read, hard to edit, and requires validation after editing.
  • We're missing the source code for the 2008.11 books.
  • In regard to the factual correctness of the documentation, do we ourselves know what still works, doesn't work, has been deprecated, replaced, etc.?


2009.6 drop

I believe we have the XML source for these books.

  • Application Packaging Developer's Guide
  • Device Driver Tutorial
  • Image Packaging System Guide
  • Getting Started With OpenSolaris
  • Managing Boot Environments
  • Memory Thread Placement and Optimization Developer's Guide
  • OpenSolaris Automated Installer Guide
  • OpenSolaris Developer's Reference Guide
  • OpenSolaris Distribution Contructor Guide
  • Solaris CIFS Administration Guide
  • Solaris Containers: Resource Management and Solaris Zones Developer's Guide
  • Solaris Dynamic Tracing Guide
  • Solaris Express Developer Edition Installation Guide: Laptop Installations
  • Solaris Express Developer Edition Release Notes
  • Solaris Express Developer Edition What's New
  • Solaris Express Installation Guide: Solaris Flash Archives (Creation and Installation)
  • Solaris Express Installation Guide: Basic Installations
  • Solaris Express Installation Guide: Custom JumpStart and Advanced Installations
  • Solaris Express Installation Guide: Network-Based Installations
  • Solaris Express Installation Guide: Planning for Installation and Upgrade
  • Solaris Express Installation Guide: Solaris Live Upgrade and Upgrade Planning
  • Solaris Express Package List
  • Solaris Modular Debugger Guide
  • Solaris Trusted Extensions Administrator's Procedures
  • Solaris Trusted Extensions Developer's Guide
  • Solaris Trusted Extensions Installation and Configuration Guide
  • Solaris Trusted Extensions Label Administration
  • Solaris Trusted Extensions Transition Guide
  • Solaris Trusted Extensions User's Guide
  • Solaris Tunable Parameters Reference Manual
  • Solaris Volume Manager System Administration Guide
  • System Administration Guide: Advanced Administration
  • System Administration Guide: Basic Administration
  • System Administration Guide: Devices and File Systems
  • System Administration Guide: IP Services
  • System Administration Guide: Naming and Directory Services (DNS, NIS, and LDAP)
  • System Administration Guide: Network Services
  • System Administration Guide: Security Services
  • System Administration Guide: Solaris Containers--Resource Management and Solaris Zones
  • System Administration Guide: Solaris Printing
  • Writing Device Drivers
  • ZFS Administration Guide


2008.11 drop

We do not have the source for these books. All that looks to be available is HTML. Presumably these books are also open source, but I am not sure they were released under PDL like the books from the 2009.06 drop.


A full list of the 2008.11 books with separate links to each directory:


Other OpenSolaris docs