Cayenne site

[Aristedes Maniatis <ar...@maniatis.org>]

On 28/04/11 5:58 PM, Andrus Adamchik wrote:
> Confluence will be decommissioned by Apache infra soon.

I'd say 'soon' will be a very many years. I don't think we should be in any hurry about this, since there is a lot of work ahead to migrate.

1. Documentation (docbook is the front runner right now I believe)
2. Site (Markdown seems preferred, but that's a lot of work since it doesn't resemble html. Perhaps we could use raw html instead and look at migrating pages one at a time, or wait for someone at Apache to write a Confluence -> markdown converter)
3. Wiki (yes, there aren't many people using it, but it would be nice to get a Cayenne wiki happening with community contributions)


Oh, I've just committed a starting point for the docbook. It is building html and pdf and I've even got the hooks in there for publishing it to people.a.o. I'd like to see us using Jenkins to publish automatically, but it seems a bit unreliable right now.

Ari

-- 
-------------------------->
Aristedes Maniatis
GPG fingerprint CBFB 84B4 738D 4E87 5E5C  5EFA EF6A 7D2E 3E49 102A

Re: Cayenne site

[Aristedes Maniatis <ar...@maniatis.org>]

On 2/05/11 12:21 AM, Aristedes Maniatis wrote:
> Oh, I've just committed a starting point for the docbook.

Some notes for anyone reviewing this:

1. You need to generate the output to see how it works. Little tricks like <?eval ${project.version}?> only show up in the output.

2. I highly recommend Oxygen Author as the best editor tool (with an almost WYSIWYG view) for dealing with docbook. Go and download the free 28 day trial (either standalone or Eclipse plugin)

3. Docbook is huge. We need to agree on a subset of elements that we will use. That will help with consistency.


We could alternatively use Markdown or some other markup language for the documentation. The downsides of that approach:

* no pdf output
* focussed on presentation rather than content (we'll be scattering the markup with divs to get it looking the way we want)
* href links between pages will be specific to the html output choices, URLs, etc That is, the output will not be as portable. In docbook I've chosen to identify each section with an unique id for the purpose of linking.

The positive of markdown is simplicity. Docbook is OK once you get used to it, but it is more complex to hand code.


Ari




-- 
-------------------------->
Aristedes Maniatis
GPG fingerprint CBFB 84B4 738D 4E87 5E5C  5EFA EF6A 7D2E 3E49 102A

Re: Cayenne site

[Mike Kienenberger <mk...@gmail.com>]

> 2. Site (Markdown seems preferred, but that's a lot of work since it doesn't
> resemble html. Perhaps we could use raw html instead and look at migrating
> pages one at a time, or wait for someone at Apache to write a Confluence ->
> markdown converter)

I was reading about markdown last week.

========================================
For any markup that is not covered by Markdown’s syntax, you simply
use HTML itself. There’s no need to preface it or delimit it to
indicate that you’re switching from Markdown to HTML; you just use the
tags.

The only restrictions are that block-level HTML elements — e.g. <div>,
<table>, <pre>, <p>, etc. — must be separated from surrounding content
by blank lines, and the start and end tags of the block should not be
indented with tabs or spaces. Markdown is smart enough not to add
extra (unwanted) <p> tags around HTML block-level tags.
========================================


So you can start by making each markdown page raw html and convert it
as desired.  Or you can take a further step and convert that into
markdown:

========================================
Also, Aaron's [html2text][] is a very handy (and free) utility for
turning HTML into Markdown-formatted plain text.

  [html2text]:          http://www.aaronsw.com/2002/html2text/
========================================

Re: Cayenne site

[Andrus Adamchik <an...@objectstyle.org>]

On May 1, 2011, at 5:21 PM, Aristedes Maniatis wrote:

> On 28/04/11 5:58 PM, Andrus Adamchik wrote:
>> Confluence will be decommissioned by Apache infra soon.
> 
> I'd say 'soon' will be a very many years. I don't think we should be in any hurry about this, since there is a lot of work ahead to migrate.

I could be mistaken, but I remember hearing from infra that soon is actually this year.

Andrus