From dev-return-1456-apmail-trafodion-dev-archive=trafodion.apache.org@trafodion.incubator.apache.org Thu Dec 3 02:00:35 2015 Return-Path: X-Original-To: apmail-trafodion-dev-archive@minotaur.apache.org Delivered-To: apmail-trafodion-dev-archive@minotaur.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id 8561418D17 for ; Thu, 3 Dec 2015 02:00:35 +0000 (UTC) Received: (qmail 20878 invoked by uid 500); 3 Dec 2015 02:00:35 -0000 Delivered-To: apmail-trafodion-dev-archive@trafodion.apache.org Received: (qmail 20837 invoked by uid 500); 3 Dec 2015 02:00:35 -0000 Mailing-List: contact dev-help@trafodion.incubator.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@trafodion.incubator.apache.org Delivered-To: mailing list dev@trafodion.incubator.apache.org Received: (qmail 20824 invoked by uid 99); 3 Dec 2015 02:00:34 -0000 Received: from Unknown (HELO spamd2-us-west.apache.org) (209.188.14.142) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 03 Dec 2015 02:00:34 +0000 Received: from localhost (localhost [127.0.0.1]) by spamd2-us-west.apache.org (ASF Mail Server at spamd2-us-west.apache.org) with ESMTP id 7ED171A2C86 for ; Thu, 3 Dec 2015 02:00:34 +0000 (UTC) X-Virus-Scanned: Debian amavisd-new at spamd2-us-west.apache.org X-Spam-Flag: NO X-Spam-Score: 2.898 X-Spam-Level: ** X-Spam-Status: No, score=2.898 tagged_above=-999 required=6.31 tests=[DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, HTML_MESSAGE=3, RCVD_IN_MSPIKE_H2=-0.001, SPF_PASS=-0.001] autolearn=disabled Authentication-Results: spamd2-us-west.apache.org (amavisd-new); dkim=pass (2048-bit key) header.d=gmail.com Received: from mx1-eu-west.apache.org ([10.40.0.8]) by localhost (spamd2-us-west.apache.org [10.40.0.9]) (amavisd-new, port 10024) with ESMTP id KEavJp8cdFjp for ; Thu, 3 Dec 2015 02:00:33 +0000 (UTC) Received: from mail-io0-f174.google.com (mail-io0-f174.google.com [209.85.223.174]) by mx1-eu-west.apache.org (ASF Mail Server at mx1-eu-west.apache.org) with ESMTPS id 6851D20C40 for ; Thu, 3 Dec 2015 02:00:32 +0000 (UTC) Received: by ioir85 with SMTP id r85so66454205ioi.1 for ; Wed, 02 Dec 2015 18:00:31 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:date:message-id:subject:from:to:content-type; bh=4fUsBnW3eItOuRp+Tpyrg4gCZwvw8/C+AF9X0Gi2Lgk=; b=YB8uafJ9Q0T1oLVayEhSHmGystY16KHFyJDColpa28qH1glz8XUkQCoNjK7nA7aL77 x/c9VvYjHvO5jyYFCoyGT+ldwDbURhBWS1KH2orBlphNdX5jmg0Fht6PGjSv7dQ9IW7I AwwT7NB8F9HvbcDtdMqt41OQWCkkpwgZdj3MP8zkqIN4/jKxLAx14ejQLJEZx774Xhmf l4H/f0g/e80SW4FuIG9SM+nPbsoF8PL4BkckhLQAX7unpLcWuMv2vYJCpT+xB+utgRzz F43Aya/hA8ayCcaV9JBBfGC56dH0mN6/HhMgjdDi0a6FJn0GRmOnCKXJQLVX57yI25eu b6PA== MIME-Version: 1.0 X-Received: by 10.107.28.13 with SMTP id c13mr6747200ioc.149.1449108031260; Wed, 02 Dec 2015 18:00:31 -0800 (PST) Received: by 10.79.96.198 with HTTP; Wed, 2 Dec 2015 18:00:31 -0800 (PST) Date: Wed, 2 Dec 2015 19:00:31 -0700 Message-ID: Subject: Proposal for documentation on website From: Gunnar Tapper To: dev@trafodion.incubator.apache.org Content-Type: multipart/alternative; boundary=001a1140a73a71cbcf0525f4c1c4 --001a1140a73a71cbcf0525f4c1c4 Content-Type: text/plain; charset=UTF-8 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/. If I am correct, then I think that the preferred layout would be: docs docs/ docs// docs///index.html (entry point to the web version of the document) docs///_chapters (web version of the document; that is, the content) docs//.pdf (PDF version of the document docs//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/ directory. 4. Create dcs_reference_guide directory 5. Copy all files from dcs/target/site to docs//dcs_reference_guide . . . n. Move docs/target/docs/Trafodion_Client_Installation_Guide.* to docs//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.* --001a1140a73a71cbcf0525f4c1c4--