You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@trafficserver.apache.org by Igor Galić <i....@brainsware.org> on 2010/12/09 23:26:24 UTC
Documentation reboot
Hi folks,
I'd like to migrate the SDK (and the admin guide too) as soon
as possible from plain HTML to plain text.
The Apache CMS: https://blogs.apache.org/infra/entry/the_asf_cms
offers a good opportunity to do exactly that, and many
Apache projects are migrating to it.
For the SDK I am proposing to split each chapter in a separate
directory, with an index.en.mdtext as the chapter's face.
My first hunch was to add chapter numbers to the directories and
files, but that would make re-structuring the documentation
more difficult.
I have removed the function reference, as I would like to link
directly to the doxygen generated APIs. Deprecated functions have
also fallen to the ax.
We'll need to migrate the CSS, as well as the pictures.
These are things I haven't given much thought to so far.
We'll also need something to generate language links.
amc has offered Perl code to generate links from the
documentation to Doxygen API. Finally, we need something
to generate the navigation.
If there's some consensus, I'll commit the structure below
to https://svn.apache.org/repos/asf/trafficserver/site/branches/ats-cms/
and start with the conversion. Indicating the progress in
a STATUS file, so that (as soon as I have tools for automation)
everybody can join the party.
sdk
├── actions-guide
│ ├── hosts-lookup-api.en.mdtext
│ └── index.en.mdtext
├── adding-statistics
│ ├── coupled-statistics.en.mdtext
│ ├── index.en.mdtext
│ └── viewing-statistics-using-traffic-line.en.mdtext
├── cache-plugin
│ ├── cache-events.en.mdtext
│ ├── index.en.mdtext
│ ├── reads-and-writes.en.mdtext
│ ├── sample-plugin.en.mdtext
│ └── state-diagram.en.mdtext
├── continuations
│ ├── how-to-activate-continuations.en.mdtext
│ ├── index.en.mdtext
│ └── writing-handler-functions.en.mdtext
├── getting-started
│ ├── a-simple-plugin.en.mdtext
│ ├── index.en.mdtext
│ ├── naming-conventions.en.mdtext
│ └── plugin-registration-and-version-checking.en.mdtext
├── header-based-plugin-examples
│ ├── basic-authorization-plugin.en.mdtext
│ ├── blacklist-plugin.en.mdtext
│ └── index.en.mdtext
├── how-to-create-trafficserver-plugins
│ ├── index.en.mdtext
│ └── roadmap-for-creating-plugins.en.mdtext
├── http-headers
│ ├── guide-to-trafficserver-http-header-system
│ │ ├── duplicate-mime-fields-are-not-coalesced.en.mdtext
│ │ ├── index.en.mdtext
│ │ ├── mime-fields-always-belong-to-an-associated-mime-header.en.mdtext
│ │ └── release-marshal-buffer-handles.en.mdtext
│ ├── http-headers.en.mdtext
│ ├── index.en.mdtext
│ ├── marshal-buffers.en.mdtext
│ ├── mime-headers.en.mdtext
│ └── urls.en.mdtext
├── http-hoooks-and-transactions
│ ├── adding-hooks.en.mdtext
│ ├── http-alternate-selection.en.mdtext
│ ├── http-sessions.en.mdtext
│ ├── http-transactions.en.mdtext
│ ├── index.en.mdtext
│ ├── initiate-http-connection.en.mdtext
│ └── intercepting-http-transactions.en.mdtext
├── http-transformation0plugin
│ ├── append-transform-plugin.en.mdtext
│ ├── index.en.mdtext
│ ├── sample-buffered-null-transformation-plugin.en.mdtext
│ └── sample-null-transformation-plugin.en.mdtext
├── index.en.mdtext
├── io-guide
│ ├── guide-to-cache-api
│ │ ├── errors.en.mdtext
│ │ ├── example.en.mdtext
│ │ ├── how-to-do-a-cache-remove.en.mdtext
│ │ ├── how-to-do-a-cache-write.en.mdtext
│ │ └── index.en.mdtext
│ ├── index.en.mdtext
│ ├── io-buffers.en.mdtext
│ ├── net-vconnections.en.mdtext
│ ├── transformations.en.mdtext
│ └── vios.en.mdtext
├── misc-interface-guide
│ ├── index.en.mdtext
│ ├── memory-allocation.en.mdtext
│ ├── thread-functions.en.mdtext
│ └── tsfopen-family.en.mdtext
├── mutex-guide
│ └── index.en.mdtext
├── new-protocol-plugins
│ └── index.en.mdtext
├── plugin-configurations
│ └── index.en.mdtext
├── plugin-management
│ ├── accessing-installed-plugin-files.en.mdtext
│ ├── guide-to-the-logging-api.en.mdtext
│ ├── index.en.mdtext
│ └── reading-trafficserver-settings-and-statistics.en.mdtext
├── preface
│ ├── how-to-use-this-book.en.mdtext
│ ├── index.en.mdtext
│ └── typographical-conventions.en.mdtext
├── remap-plugin
│ ├── example-query-remap.en.mdtext
│ ├── function-reference.en.mdtext
│ └── index.en.mdtext
├── sample-source-code
│ └── index.en.mdtext
└── troubleshooting-tips
├── debugging-memory-leaks.en.mdtext
├── index.en.mdtext
├── unable-to-debug-tags.en.mdtext
├── unable-to-load-plugins.en.mdtext
└── using-a-debugger.en.mdtext
i
--
Igor Galić
Tel: +43 (0) 664 886 22 883
Mail: i.galic@brainsware.org
URL: http://brainsware.org/
Re: Documentation reboot
Posted by Miles Libbey <mi...@yahoo-inc.com>.
Other parts of the new implementation that I think we'll need to add:
- a way to include a header and footer section. If there becomes a need to change to a new CSS file/modify the search box; putting a new copywrite etc, changing in 1 file is much much nicer than in every file. The current site uses SSI to achieve this -- many wiki languages have similar concepts, but I suppose that the text to html conversion script could also put them in.
- similarly, the navigation probably needs a bit more thought (as you point out). The current SDK site has a file that has the file structure (ie, "URLs" is a subnode of the "HTTP Headers" chapter, and is generated via javascript. The top navigation (next/previous) is done by hand in the individual file.
- localization. The current site doesn't have any way to localize. Its great that the new one has a language tag on the file name. In httpd land, once an english file is changed, a script goes through and finds the corresponding other language files and modifies them to indicate the english version has changed. IMHO, this seems very clunky, relying on localizers to be able to diff files ... but its something. Is there a similar process in this new CMS?
miles
On Dec 9, 2010, at 2:26 PM, Igor Galić wrote:
>
> Hi folks,
>
> I'd like to migrate the SDK (and the admin guide too) as soon
> as possible from plain HTML to plain text.
> The Apache CMS: https://blogs.apache.org/infra/entry/the_asf_cms
> offers a good opportunity to do exactly that, and many
> Apache projects are migrating to it.
>
> For the SDK I am proposing to split each chapter in a separate
> directory, with an index.en.mdtext as the chapter's face.
>
> My first hunch was to add chapter numbers to the directories and
> files, but that would make re-structuring the documentation
> more difficult.
>
> I have removed the function reference, as I would like to link
> directly to the doxygen generated APIs. Deprecated functions have
> also fallen to the ax.
>
> We'll need to migrate the CSS, as well as the pictures.
> These are things I haven't given much thought to so far.
> We'll also need something to generate language links.
> amc has offered Perl code to generate links from the
> documentation to Doxygen API. Finally, we need something
> to generate the navigation.
>
> If there's some consensus, I'll commit the structure below
> to https://svn.apache.org/repos/asf/trafficserver/site/branches/ats-cms/
> and start with the conversion. Indicating the progress in
> a STATUS file, so that (as soon as I have tools for automation)
> everybody can join the party.
>
> sdk
> ├── actions-guide
> │ ├── hosts-lookup-api.en.mdtext
> │ └── index.en.mdtext
> ├── adding-statistics
> │ ├── coupled-statistics.en.mdtext
> │ ├── index.en.mdtext
> │ └── viewing-statistics-using-traffic-line.en.mdtext
> ├── cache-plugin
> │ ├── cache-events.en.mdtext
> │ ├── index.en.mdtext
> │ ├── reads-and-writes.en.mdtext
> │ ├── sample-plugin.en.mdtext
> │ └── state-diagram.en.mdtext
> ├── continuations
> │ ├── how-to-activate-continuations.en.mdtext
> │ ├── index.en.mdtext
> │ └── writing-handler-functions.en.mdtext
> ├── getting-started
> │ ├── a-simple-plugin.en.mdtext
> │ ├── index.en.mdtext
> │ ├── naming-conventions.en.mdtext
> │ └── plugin-registration-and-version-checking.en.mdtext
> ├── header-based-plugin-examples
> │ ├── basic-authorization-plugin.en.mdtext
> │ ├── blacklist-plugin.en.mdtext
> │ └── index.en.mdtext
> ├── how-to-create-trafficserver-plugins
> │ ├── index.en.mdtext
> │ └── roadmap-for-creating-plugins.en.mdtext
> ├── http-headers
> │ ├── guide-to-trafficserver-http-header-system
> │ │ ├── duplicate-mime-fields-are-not-coalesced.en.mdtext
> │ │ ├── index.en.mdtext
> │ │ ├── mime-fields-always-belong-to-an-associated-mime-header.en.mdtext
> │ │ └── release-marshal-buffer-handles.en.mdtext
> │ ├── http-headers.en.mdtext
> │ ├── index.en.mdtext
> │ ├── marshal-buffers.en.mdtext
> │ ├── mime-headers.en.mdtext
> │ └── urls.en.mdtext
> ├── http-hoooks-and-transactions
> │ ├── adding-hooks.en.mdtext
> │ ├── http-alternate-selection.en.mdtext
> │ ├── http-sessions.en.mdtext
> │ ├── http-transactions.en.mdtext
> │ ├── index.en.mdtext
> │ ├── initiate-http-connection.en.mdtext
> │ └── intercepting-http-transactions.en.mdtext
> ├── http-transformation0plugin
> │ ├── append-transform-plugin.en.mdtext
> │ ├── index.en.mdtext
> │ ├── sample-buffered-null-transformation-plugin.en.mdtext
> │ └── sample-null-transformation-plugin.en.mdtext
> ├── index.en.mdtext
> ├── io-guide
> │ ├── guide-to-cache-api
> │ │ ├── errors.en.mdtext
> │ │ ├── example.en.mdtext
> │ │ ├── how-to-do-a-cache-remove.en.mdtext
> │ │ ├── how-to-do-a-cache-write.en.mdtext
> │ │ └── index.en.mdtext
> │ ├── index.en.mdtext
> │ ├── io-buffers.en.mdtext
> │ ├── net-vconnections.en.mdtext
> │ ├── transformations.en.mdtext
> │ └── vios.en.mdtext
> ├── misc-interface-guide
> │ ├── index.en.mdtext
> │ ├── memory-allocation.en.mdtext
> │ ├── thread-functions.en.mdtext
> │ └── tsfopen-family.en.mdtext
> ├── mutex-guide
> │ └── index.en.mdtext
> ├── new-protocol-plugins
> │ └── index.en.mdtext
> ├── plugin-configurations
> │ └── index.en.mdtext
> ├── plugin-management
> │ ├── accessing-installed-plugin-files.en.mdtext
> │ ├── guide-to-the-logging-api.en.mdtext
> │ ├── index.en.mdtext
> │ └── reading-trafficserver-settings-and-statistics.en.mdtext
> ├── preface
> │ ├── how-to-use-this-book.en.mdtext
> │ ├── index.en.mdtext
> │ └── typographical-conventions.en.mdtext
> ├── remap-plugin
> │ ├── example-query-remap.en.mdtext
> │ ├── function-reference.en.mdtext
> │ └── index.en.mdtext
> ├── sample-source-code
> │ └── index.en.mdtext
> └── troubleshooting-tips
> ├── debugging-memory-leaks.en.mdtext
> ├── index.en.mdtext
> ├── unable-to-debug-tags.en.mdtext
> ├── unable-to-load-plugins.en.mdtext
> └── using-a-debugger.en.mdtext
>
>
> i
>
> --
> Igor Galić
>
> Tel: +43 (0) 664 886 22 883
> Mail: i.galic@brainsware.org
> URL: http://brainsware.org/