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 20:01:35 GMT
No, it's not. The source is in Word format, which has been updated with
Apache Licenses.

On Thu, Dec 3, 2015 at 12:18 PM, Roberta Marton <roberta.marton@esgyn.com>
wrote:

> Is the documentation in xml format actually good?  I was unable to access
> the information - but it could be operator error.
>
>     Roberta
>
> -----Original Message-----
> From: Steve Varnau [mailto:steve.varnau@esgyn.com]
> Sent: Thursday, December 3, 2015 11:10 AM
> To: dev@trafodion.incubator.apache.org
> Subject: RE: Proposal for documentation on website
>
> The PDF's are generated. I don't think we should be putting generated files
> in the source. The XML files there now are the sources, even if they are
> not
> yet in the preferred format, so why not include them?
>
> --Steve
>
>
> > -----Original Message-----
> > From: Roberta Marton [mailto:roberta.marton@esgyn.com]
> > Sent: Thursday, December 3, 2015 10:30 AM
> > To: dev@trafodion.incubator.apache.org
> > Subject: RE: Proposal for documentation on website
> >
> > I was planning on copying the pdf and word documents that Gunnar
> > produced
> > to:
> >
> > /docs/src/resource/docs and include them in the source tar.
> >
> > I was not planning on including the existing documents in the source
> > tar, e.g. docs/client_install
> >
> > Should  I do something else?
> >
> >     Roberta
> >
> > -----Original Message-----
> > From: Steve Varnau [mailto:steve.varnau@esgyn.com]
> > Sent: Thursday, December 3, 2015 10:25 AM
> > To: dev@trafodion.incubator.apache.org
> > Subject: RE: Proposal for documentation on website
> >
> > Gunnar,
> >
> > Yes, it is okay by me for generated PDF to be in the site repo, but
> > I'd prefer not to have that format checked into the source repo. It'll
> > be great once we have the asciidoc versions there.  I know -- one step
> > at a time!
> >
> > --Steve
> >
> >
> > > -----Original Message-----
> > > From: Gunnar Tapper [mailto:tapper.gunnar@gmail.com]
> > > Sent: Thursday, December 3, 2015 9:52 AM
> > > To: dev@trafodion.incubator.apache.org
> > > Subject: Re: Proposal for documentation on website
> > >
> > > 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
> > > > > .g
> > > > > it
> > > > > 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
> > > > > .g
> > > > > it
> > > > > 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
> > > > > .g it 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.*
>



-- 
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