Enhancements to the documentation CMS

["Alan M. Carroll" <am...@network-geographics.com>]

I made a few tweaks to the documentation generator.

* A navigation bar is now available. This is auto generated if there id a file named "order.txt" in the directory that contains the pages. This file is simply a white space separated list of the stems for the pages, in the order in which they should be connected. If the actual content is nested in a directory (e.g., monitoring-traffics/index.en.mdtext) then the stem should be the directory name. The logic tries to be clever about figuring this out, and will check an order.txt in the nested directory and the containing directory and use the one where it finds the stem. You can see examples of all cases in the docs/trunk/admin directory.

The navigation bar can be overridden per file as well. You can set a header variable "Navigation" which should be a white space separated list of links in Markdown format. These then become the elements of the Navigation bar (anything in order.txt is ignored for such a file). See docs/trunk/admin/index.en.mdtext for an example.

* External variables are now available. When page is processed, the view logic will look for a file named "vars.txt" in each directory from the base directory for the document (trunk - it looks for the 'STATUS' file as a marker of topness) down to the directory containing the page. Each file is read and the variables added. These are done from trunk to local so that "closer" files override more distant ones. This means common information can be shared in such files rather than being duplicated in multiple content files. E.g., "Administrator's Guide" now comes from a vars.txt rather than all of the admin source files. Any variable defined in the source file overrides the external value (if any) for that variable.

* We're using a style sheet now. You can find it at content/styles/ts.css in the doc source tree.

The internal links aren't quite right yet, so you can look at these

http://trafficserver.staging.apache.org/docs/trunk/admin/configuration-files/files.en.html

http://trafficserver.staging.apache.org/docs/trunk/admin/

Re: Enhancements to the documentation CMS

[Wyn Williams <he...@gmail.com>]

I still say use Plone 4, free hosting and amazing power...

On Wed, 2011-03-09 at 16:23 -0600, Alan M. Carroll wrote:

> Wednesday, March 9, 2011, 3:42:56 PM, you wrote:
> 
> > More items to the wish list:
> 
> > * Convert [TS-(\d+)] into a link to https://issues.apache.org/jira/browse/TS-$1
> 
> Do we want to always do that, or have a notation saying "link it"? E.g., $TS-700$ instead of just TS-700. I prefer the former because if the later turns out to be a problem, it's very hard to work around. Remember the stars.
> 
> > * Add some mechanism to link to Doxygen. Right now all links to doxygen are marked as
> >   [TSFooBar](/link/to/doxygen)
> 
> I will take charge of that, I need it for another client project anyway. One aspect of this is that I will almost certainly implement something that supports the notation noted above, so we can leverage that with little cost. My view on Doxygen linkage is something on the order of  $api "ts::Configuration::load"$ which creates a link to the Doxygen for that name. I already have the code base to set this up (WikiVars) and it's easy to extend later as desired.
> 

Re: Enhancements to the documentation CMS

[Igor Galić <i....@brainsware.org>]

----- Original Message -----
> Wednesday, March 9, 2011, 3:42:56 PM, you wrote:
> 
> > More items to the wish list:
> 
> > * Convert [TS-(\d+)] into a link to
> > https://issues.apache.org/jira/browse/TS-$1
> 
> Do we want to always do that, or have a notation saying "link it"?
> E.g., $TS-700$ instead of just TS-700. I prefer the former because
> if the later turns out to be a problem, it's very hard to work
> around. Remember the stars.

I do not much care for notation. But we should remember one thing:
Markdown is Text. It can be effortlessly read as text. We should
try not to destroy that aspect ;)

Furthermore, it's possible to convert it any format desired.
It would be nice retain that as well -- Leif mentioned he'd
really like to see PDF version of the docs.

> > * Add some mechanism to link to Doxygen. Right now all links to
> > doxygen are marked as
> >   [TSFooBar](/link/to/doxygen)
> 
> I will take charge of that, I need it for another client project
> anyway. One aspect of this is that I will almost certainly implement
> something that supports the notation noted above, so we can leverage
> that with little cost. My view on Doxygen linkage is something on
> the order of  $api "ts::Configuration::load"$ which creates a link
> to the Doxygen for that name. I already have the code base to set
> this up (WikiVars) and it's easy to extend later as desired.

Awesome!

i

-- 
Igor Galić

Tel: +43 (0) 664 886 22 883
Mail: i.galic@brainsware.org
URL: http://brainsware.org/

Re: Enhancements to the documentation CMS

["Alan M. Carroll" <am...@network-geographics.com>]

Wednesday, March 9, 2011, 3:42:56 PM, you wrote:

> More items to the wish list:

> * Convert [TS-(\d+)] into a link to https://issues.apache.org/jira/browse/TS-$1

Do we want to always do that, or have a notation saying "link it"? E.g., $TS-700$ instead of just TS-700. I prefer the former because if the later turns out to be a problem, it's very hard to work around. Remember the stars.

> * Add some mechanism to link to Doxygen. Right now all links to doxygen are marked as
>   [TSFooBar](/link/to/doxygen)

I will take charge of that, I need it for another client project anyway. One aspect of this is that I will almost certainly implement something that supports the notation noted above, so we can leverage that with little cost. My view on Doxygen linkage is something on the order of  $api "ts::Configuration::load"$ which creates a link to the Doxygen for that name. I already have the code base to set this up (WikiVars) and it's easy to extend later as desired.

Re: Enhancements to the documentation CMS

[Igor Galić <i....@brainsware.org>]

Hey folks,

here's some progress report.

I'm currently working on migrating the site to Markdown too,
because I think it makes sense, it's much easier on the editing.

Might be useful to add RSS Feeds to index and downloads

We also need to re-integrate the google Search for the docs.

> Now, here's a couple other items from my wish-list:
> 
> The CSS needs tweaking, both amc and me are.. slightly inhibited in
> that regard, so we'd appreciate input, patches, etc, from everyone
> who
> has any kind of the aesthetic taste we lack :)
> 
> In particular I noticed that
> 
> * the definition lists which we use extensively look awful.
> * fonts should match the front page: http://trafficserver.apache.org/
>   instead of being defaults (usually something like Times New Roman)
> * make text (of normal content) justified?
> * break terribly long lines.

More items to the wish list:

* Convert [TS-(\d+)] into a link to https://issues.apache.org/jira/browse/TS-$1

* Add some mechanism to link to Doxygen. Right now all links to doxygen are marked as
  [TSFooBar](/link/to/doxygen)

i

-- 
Igor Galić

Tel: +43 (0) 664 886 22 883
Mail: i.galic@brainsware.org
URL: http://brainsware.org/

Re: Enhancements to the documentation CMS

[Igor Galić <i....@brainsware.org>]

Inspired by reading Rich Bowen's presentation:
http://www.slideshare.net/rbowen/write-a-better-fm
which everybody should read!

----- Original Message -----
> Due to the "it's never enough" effect I have extend the use specified
> nav bar links syntax. If you add a link that has a name of "Top",
> "Back", or "Next" (the auto-generated names) and a URL of '*', then
> the '*' will be changed to the corresponding generated value. If the
> generated value doesn't exist (e.g., you used 'Back' in the first
> item) then the link item is silently discarded.

I've already suggested in TS-694 to *always* add a language links,
if the link would be *none* -- replace it with a Link to our wiki
on how to contribute to our documentation.

Now, here's a couple other items from my wish-list:

The CSS needs tweaking, both amc and me are.. slightly inhibited in
that regard, so we'd appreciate input, patches, etc, from everyone who
has any kind of the aesthetic taste we lack :)

In particular I noticed that

* the definition lists which we use extensively look awful.
* fonts should match the front page: http://trafficserver.apache.org/
  instead of being defaults (usually something like Times New Roman)
* make text (of normal content) justified?
* break terribly long lines.

Me and my army of monkeys are currently busy fixing the admin/
content's general markdown style, since it was just migrated
by script. Both hands are tied to conducting the monkey's
work, so any helping hand is more than welcome!


i


-- 
Igor Galić

Tel: +43 (0) 664 886 22 883
Mail: i.galic@brainsware.org
URL: http://brainsware.org/

Re: Enhancements to the documentation CMS

["Alan M. Carroll" <am...@network-geographics.com>]

Due to the "it's never enough" effect I have extend the use specified nav bar links syntax. If you add a link that has a name of "Top", "Back", or "Next" (the auto-generated names) and a URL of '*', then the '*' will be changed to the corresponding generated value. If the generated value doesn't exist (e.g., you used 'Back' in the first item) then the link item is silently discarded.

Re: Enhancements to the documentation CMS

[Igor Galić <i....@brainsware.org>]

----- Original Message -----
> I made a few tweaks to the documentation generator.
> 
> * A navigation bar is now available. This is auto generated if there
> id a file named "order.txt" in the directory that contains the
> pages. This file is simply a white space separated list of the stems
> for the pages, in the order in which they should be connected. If
> the actual content is nested in a directory (e.g.,
> monitoring-traffics/index.en.mdtext) then the stem should be the
> directory name. The logic tries to be clever about figuring this
> out, and will check an order.txt in the nested directory and the
> containing directory and use the one where it finds the stem. You
> can see examples of all cases in the docs/trunk/admin directory.

This doesn't quite work yet recursively:
http://trafficserver.staging.apache.org/docs/trunk/sdk/

Try clicking through he book with the Next links

i

-- 
Igor Galić

Tel: +43 (0) 664 886 22 883
Mail: i.galic@brainsware.org
URL: http://brainsware.org/