trafodion-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gunnar Tapper <tapper.gun...@gmail.com>
Subject Re: Proposal for documentation on website
Date Thu, 03 Dec 2015 17:51:50 GMT
Hi Steve,

We have those documents in Word/PDF format at the momement plus the
maybe-yet-to-be-completed XML-to-asciidoc format. For now, I propose that
we provide PDF access and then complete the migration to asciidoc later. OK?

Thanks,

Gunnar

On Thu, Dec 3, 2015 at 10:35 AM, Steve Varnau <steve.varnau@esgyn.com>
wrote:

> Gunnar,
>
> For the last four, you list as word/pdf, but the source xml files for them
> is in the docs tree in the incubator-trafodion repo. I believe you are
> right, the goal was to convert them from xml to asciidoc.
>
> --Steve
>
>
> > -----Original Message-----
> > From: Gunnar Tapper [mailto:tapper.gunnar@gmail.com]
> > Sent: Wednesday, December 2, 2015 6:01 PM
> > To: dev@trafodion.incubator.apache.org
> > Subject: Proposal for documentation on website
> >
> > Hi,
> >
> > The Trafodion documentation is a bit challenging to deal with at the
> > moment. At the moment, I know of the following manuals/guides:
> >
> >
> >    - DCS Reference Guide (asciidoc) -- dcs/src/main/asciidoc
> >    - DCS API Docs (Javadoc)
> >    - REST Server Reference Guide (asciidoc) --
> core/rest/src/main/asciidoc
> >    - REST API Docs (Javadoc)
> >    - Client Installation Guide (Word/PDF) -- docs/resources/docs
> >    - Command Interface Guide (Word/PDF) -- docs/resources/docs
> >    - odb User Guide (Word/PDF) -- docs/resources/docs
> >    - SQL Reference Guide (Word/PDF) -- docs/resources/docs
> >
> > The documentation should be part of a release's source tree and,
> > therefore,
> > be versioned. Further, the documentation should be available on the
> > website.
> >
> > The website is rendered into docs/target. The documents go into
> > docs/target/docs, which means that there will be an
> > incubator.trafodion.apache.org/docs directory for the website.
> >
> > The content of docs/target is checked into
> > https://git-wip-us.apache.org/repos/asf/incubator-trafodion-site.git via
> > manual checkout, copy, checkin and then svnpubsub, which does the actual
> > publication.
> >
> > From what I understand, the goal is to convert all documentation into
> > asciidoc providing both web and PDF version of each document. As such,
> I'd
> > believe that the web site's docs directory should be organized per
> > version;
> > that is, docs/<version>. If I am correct, then I think that the preferred
> > layout would be:
> >
> > docs
> > docs/<version>
> > docs/<version>/<document>
> > docs/<version>/<document>/index.html (entry point to the web version
of
> > the
> > document)
> > docs/<version>/<document>/_chapters (web version of the document; that
> is,
> > the content)
> > docs/<version>/<document/<document>.pdf (PDF version of the document
> > docs/<version>/document/apidocs/index.html (entry point to the web
> version
> > of the API docs, if they exist)
> >
> > Using DCS as an example, we'd have
> >
> > docs/1.3.0/dcs_reference_guide/index.html
> > docs/1.3.0/dcs_reference_guide/_chapters
> > docs/1.3.0/dcs_reference_guide/dcs_reference_guide_1_3_0.pdf
> > docs/1.3.0/dcs_reference_guide/apidocs/index.html
> >
> > Is this an OK organization? If so, I can write up instructions for how to
> > copy the different documents to their target
> > https://git-wip-us.apache.org/repos/asf/incubator-trafodion-site.git
> > directories.
> > In essence, the procedure would be:
> >
> > 1. Run the release build.
> > 2. Checkout
> > https://git-wip-us.apache.org/repos/asf/incubator-trafodion-site.git
> > 3. Create the new docs/<version> directory.
> > 4. Create dcs_reference_guide directory
> > 5. Copy all files from dcs/target/site to
> > docs/<version>/dcs_reference_guide
> > .
> > .
> > .
> > n. Move docs/target/docs/Trafodion_Client_Installation_Guide.* to
> > docs/<version>/client_installation_guide
> > .
> > .
> > .
> >
> > Admittedly, this is both manual and clumsy but I think it organizes the
> > information in a manner that allows for future automation.
> >
> > Comments? Suggestions?
> >
> > --
> > Thanks,
> >
> > Gunnar
> > *If you think you can you can, if you think you can't you're right.*
>



-- 
Thanks,

Gunnar
*If you think you can you can, if you think you can't you're right.*

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message