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 22:13:56 GMT
They are in shape to be in 1.3 but the source is in Word. Is there an
alternative repository for .doc, .ppt, etc files? We do want such documents
to be protected and under change control, right? The same question applies
to source for images used in asciidoc documents...
On Dec 3, 2015 2:16 PM, "Steve Varnau" <steve.varnau@esgyn.com> wrote:

> Okay, then it sounds like the docs can be generated to PDF to post on the
> project site, but are not in shape to include in the 1.3 code release at
> all.
>
> --Steve
>
>
> > -----Original Message-----
> > From: Gunnar Tapper [mailto:tapper.gunnar@gmail.com]
> > Sent: Thursday, December 3, 2015 12:02 PM
> > To: dev@trafodion.incubator.apache.org
> > Subject: Re: Proposal for documentation on website
> >
> > 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