Simon Pepping | 5 Jul 17:13 2010
Picon

Re: svn commit: r960618 [1/3] - in /xmlgraphics/fop/branches/fop-1_0

On Mon, Jul 05, 2010 at 03:05:56PM -0000, spepping <at> apache.org wrote:
> URL: http://svn.apache.org/viewvc?rev=960618&view=rev
> Log:
> First changes for the release, mainly documentation changes
> 
> Modified:
>     xmlgraphics/fop/branches/fop-1_0/NOTICE
>     xmlgraphics/fop/branches/fop-1_0/README
>     xmlgraphics/fop/branches/fop-1_0/build.xml
>     xmlgraphics/fop/branches/fop-1_0/fop.bat
>     xmlgraphics/fop/branches/fop-1_0/src/documentation/content/xdocs/compliance.ihtml
>     xmlgraphics/fop/branches/fop-1_0/src/documentation/content/xdocs/dev/release.xml
>     xmlgraphics/fop/branches/fop-1_0/src/documentation/content/xdocs/download.xml
>     xmlgraphics/fop/branches/fop-1_0/src/documentation/content/xdocs/index.xml
>     xmlgraphics/fop/branches/fop-1_0/src/documentation/content/xdocs/site.xml
>     xmlgraphics/fop/branches/fop-1_0/status.xml

In README: Is the list of included files without the ASL2 complete?

In README: Check the list of major changes which I picked from all
changes in status.xml.

In index.html and trunk/output.html: output formats: I changed PNG to
PNG/TIFF. Is TXT still a - to a lesser extent - supported output
format?

In index.html, last paragraph: I changed XML 1.0 to XML 1.1 and XSLT
1.0 to XSLT 1.0 and 2.0.

In compliance, I kept only 0.95, 1.0 and trunk. This caused extensive
(Continue reading)

Jeremias Maerki | 5 Jul 19:13 2010
Picon

Re: svn commit: r960618 [1/3] - in /xmlgraphics/fop/branches/fop-1_0

On 05.07.2010 17:13:32 Simon Pepping wrote:
> On Mon, Jul 05, 2010 at 03:05:56PM -0000, spepping <at> apache.org wrote:
> > URL: http://svn.apache.org/viewvc?rev=960618&view=rev
> > Log:
> > First changes for the release, mainly documentation changes
> > 
> > Modified:
> >     xmlgraphics/fop/branches/fop-1_0/NOTICE
> >     xmlgraphics/fop/branches/fop-1_0/README
> >     xmlgraphics/fop/branches/fop-1_0/build.xml
> >     xmlgraphics/fop/branches/fop-1_0/fop.bat
> >     xmlgraphics/fop/branches/fop-1_0/src/documentation/content/xdocs/compliance.ihtml
> >     xmlgraphics/fop/branches/fop-1_0/src/documentation/content/xdocs/dev/release.xml
> >     xmlgraphics/fop/branches/fop-1_0/src/documentation/content/xdocs/download.xml
> >     xmlgraphics/fop/branches/fop-1_0/src/documentation/content/xdocs/index.xml
> >     xmlgraphics/fop/branches/fop-1_0/src/documentation/content/xdocs/site.xml
> >     xmlgraphics/fop/branches/fop-1_0/status.xml
> 
> In README: Is the list of included files without the ASL2 complete?

It is now, I believe.

> In README: Check the list of major changes which I picked from all
> changes in status.xml.

Added the missing event handling framework.

> In index.html and trunk/output.html: output formats: I changed PNG to
> PNG/TIFF. Is TXT still a - to a lesser extent - supported output
> format?
(Continue reading)

Vincent Hennebert | 6 Jul 21:30 2010
Picon

Re: Switching to DocBook [was: svn commit: r960618 [1/3] - in /xmlgraphics/fop/branches/fop-1_0]

Hi,

Jeremias Maerki wrote:
> On 05.07.2010 17:13:32 Simon Pepping wrote:
<snip/>
>> In compliance, I kept only 0.95, 1.0 and trunk. This caused extensive
>> changes to comments.
> 
> I guess keeping track of various versions on the website is one of the
> biggest issues why doing FOP releases is so hard. I keep wondering if we
> should not transform the actual product information to DocBook. But that,
> too, takes a lot of (initial) work.

Interesting. Do you mean completely replacing Forrest by a DocBook-based
framework? Because otherwise that would only add up to the complexity
IMO.

From my experience I see the following pros and cons of using DocBook:
Pros:
• stable, well-known, well supported format;
• very well documented: http://www.docbook.org/tdg/en/html/docbook.html
• geared towards technical documentation which exactly matches our
  needs;
• HTML output easily customizable by CSS;
• PDF output easily customizable by XSLT;
• well supported, excellently documented official stylesheets:
  http://www.sagehill.net/docbookxsl/
• I like it ;-)

Cons:
(Continue reading)

Jeremias Maerki | 6 Jul 22:08 2010
Picon

Re: Switching to DocBook [was: svn commit: r960618 [1/3] - in /xmlgraphics/fop/branches/fop-1_0]

Hi Vincent,

I was actually thinking of converting only the product docs, not the
website. For just HTML output, I find Forrest quite nice, but the
linking for the various versions creates a lot of overhead for a release.
And that's basically what triggered that thought.

Basically, I'd suggest to do this:
- Basic website with Forrest with links to versioned product docs and
Javadoc.
- Product docs converted to DocBook, offering HTML and PDF versions
similar to the SVN Book. Including FAQ.
- Move developer docs entirely to the Wiki where it is more likely to be
maintained. Developer docs in two places is a bad idea.

One problem remains for which I don't have a good answer: the compliance
page which is a bit hard to maintain.

On 06.07.2010 21:30:46 Vincent Hennebert wrote:
> Hi,
> 
> Jeremias Maerki wrote:
> > On 05.07.2010 17:13:32 Simon Pepping wrote:
> <snip/>
> >> In compliance, I kept only 0.95, 1.0 and trunk. This caused extensive
> >> changes to comments.
> > 
> > I guess keeping track of various versions on the website is one of the
> > biggest issues why doing FOP releases is so hard. I keep wondering if we
> > should not transform the actual product information to DocBook. But that,
(Continue reading)

Simon Pepping | 8 Jul 21:32 2010
Picon

Re: Switching to DocBook [was: svn commit: r960618 [1/3] - in /xmlgraphics/fop/branches/fop-1_0]

I spent time on the documentation in three ways:

1. Updating the links from 0.95 to 1.0 and from 0.94 to 0.95. This can
be avoided if we call the directories 'latest' and 'previous'.

2. Updating the compliance page. I did this with emacs regexes, but
they are tricky. I think the setup of the page needs to be changed to
make it scriptable.

3. Updating the documentation. Some documentation is well maintained
between releases, other documentation is left to become outdated. This
will always be a problem. In this release I am trying to make a slight
paradigm shift: Forget about 0.20.x, it is too far in the past (but
Pascal just wrote that there are still questions about it). Such
changes will always occur and take time. I would call it pre-release
work rather than part of the release build.

I cannot see if Docbook documents would be easier to maintain. It
would certainly get them out of the web site structure, which may
encourage people to modify them without fear to get tangled in
structural problems.

An effort to script the release build, including modifying the
documentation automatically as much as possible, will reveal how
difficult and time consuming a release really is, apart from
pre-release work like updating the README, news, and taking a good
look at other documents.

Simon

(Continue reading)


Gmane