Wed Mar 21, 2018 10:44 am
Login Register Lost Password? Contact Us

How Do I View or Edit Docs for a Branch?

A place for developers to ask questions about contributing to the open source code base

Fri Apr 04, 2014 7:14 pm Change Time Zone

I recently built the HPCC-Platform on Linux. I noticed that there is a docs subfolder and that it contains a lot of XML files that correspond to the sections of the various manuals. When I open the XML documents with the browser, I see the XML and a note that says no style-sheet found. Is there a program I should use in Linux to view and/or edit the documentation?
Posts: 28
Joined: Tue Jun 18, 2013 2:56 pm

Fri Apr 04, 2014 7:33 pm Change Time Zone


Those XML files are in standard Docbook format, so any docbook-compliant xml editor should work. We use XMLmind ( for all of our editing.

If you plan on making significant contributions to the docs, then you should coordinate with Jim DeFabia to ensure that you follow all of our standard conventions. The docs are part of our automated build process, so introducing changes that don't conform to the established practice could potentially "break the world" on a nightly basis. :)

Therefore, if you simply intend to make minor changes (fix typos, add a few comments, etc.) then you should just submit a JIRA ticket against the docs and Jim's team will take care of it.


Community Advisory Board Member
Community Advisory Board Member
Posts: 1341
Joined: Wed Oct 26, 2011 7:40 pm

Fri Apr 04, 2014 8:40 pm Change Time Zone

At this point, I'm mostly interested in just viewing the documentation. I discovered that I can open individual XML files with LibreOffice in my Ubuntu system and it displays them in WYSIWYG.

When I build the HPCC-Platform, the last step did a build of "docs". Does this generate some master file that allows me to browse the documents?
Posts: 28
Joined: Tue Jun 18, 2013 2:56 pm

Tue Apr 08, 2014 1:29 pm Change Time Zone

If you are mostly interested in viewing the documentation, then reading them in your WYSIWYG editor should work nicely but the intended formatting will not be 100% identical. You can also download the PDFs from the portal, too.

We build the outputs (PDF, CHM, HTML, etc) using transformation templates (XSLT) and formatting object processors (FOP) which are also in our open source repository. This produces the look and feel we want. WYSIWYG editors do not use our formatting templates or CSS files, so some of the custom formatting features our templates support won't display in an editor.

If you want to edit, you can contribute in the same manner as any of our source code or you can open Jira issues to request edits. We welcome feedback and contributions.

Posts: 128
Joined: Wed May 18, 2011 1:35 pm

Tue Apr 08, 2014 1:52 pm Change Time Zone

Is there a make target I should use to build the documentation?
Posts: 28
Joined: Tue Jun 18, 2013 2:56 pm

Tue Apr 08, 2014 6:56 pm Change Time Zone

Yes we have a CMAKE target, cmake_minimum_required(VERSION 2.8) PROJECT(docs)...
just check out the CMakeLists.txt files.

In addition There are some custom macros and other dependencies, most of which are all out there on github. There are some external components, such as XSLT Processor, the Apache FOP, which are going to be required, and configured to work with these sources.

It would be much easier, and a more effective use of your time, to just download the PDFs from the portal.
Posts: 5
Joined: Tue Apr 08, 2014 6:35 pm

Return to Contributors

Who is online

Users browsing this forum: No registered users and 1 guest