xmlgraphics-general mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Vincent Hennebert <vhenneb...@gmail.com>
Subject Re: documentation!???
Date Mon, 11 Feb 2013 10:37:34 GMT
On 11/02/13 09:10, Pascal Sancho wrote:
> Hi,
> 
> IMHO, mixing website and FOP doc doesn't help. Look at BATIK javadoc:
> with the current process, there is no chance to manage it correctly.
> If website and various docs were in separate processes, we could
> attach easily docs to the appropriate project.
> I agree with GA's old remark: FOP doc should remain in a xml form to
> have a chance to get it in either a web form, or a pdf form.
> On the other side, Website in its current form is very easy to maintain.
> So, a better solution should be:
>  - FOP doc in FOP project, if possible in a form that can be easily
> transformed to either html, or pdf (docbook?)
>  - FOP website in markdown format (IMO, repository location has no
> importance; can be either in XGC CMS or FOP specific CMS
>  - FOP javadoc, in the same way as FOP doc.
> 
> WDYT?

This is actually what other projects seem to be doing (keeping the
general information on one side, and the software documentation on
another). As discussions were occurring on the infra@ mailing list about
the CMS, it became apparent to me that we didn’t have to use the CMS for
the documentation. In fact, we didn’t have to use the CMS at all.

What we did have to do is to use svnpubsub to publish our website,
either through the CMS or by other means. Some information can be found
in [1], although I couldn’t find precise instructions about how to use
svnpubsub outside the CMS. But it seems to me that all we could have
done is slightly alter the publish part of the Forrest-based website
generation, in order to commit to an svnpubsub-managed repository
instead of the one on people.apache.org.

[1] http://www.apache.org/dev/project-site.html

All that said, I certainly don’t regret our move from Forrest which
I never really mastered and never felt inclined either to learn
properly.

But if we want to have the documentation back together with the source
code, the way to go is to use svnpubsub to update the corresponding
parts of the website (infra won’t accept to install a custom svn commit
hook I believe).

We can keep it in the Markdown format, or we could convert it back to
some flavour of xml. DocBook was mentioned some time ago and would
probably be better supported than xdoc.

Or, we can leave things as they are, and when we create a release, we
can somehow pull the relevant tab from the website and pack it with the
source code. This would be a slightly altered version of option #1
mentioned earlier.

Keeping the doc in the CMS (option #1) has the advantage that we have
a uniform way to write documentation, and we can use the CMS gui.

Keeping the doc with the source (option #2) has the advantage of
requiring only 1 patch for a change, instead of two separate ones, one
for the source and one for the documentation.


> 2013/2/11 Clay Leeds <the.webmaestro@gmail.com>:
>> On Feb 10, 2013, at 1:03 PM, Glenn Adams <glenn@skynav.com> wrote:
>>> On Sun, Feb 10, 2013 at 10:50 AM, Clay Leeds <the.webmaestro@gmail.com>wrote:
>>>> Hi folks,
>>>>
>>>> I've eradicated Forrest-based documentation from FOP. Now we need to
>>>> ensure that FOP builds properly.
>>>>
>>>> BTW, I also need to do the same for Batik and XML Graphics Commons, but I
>>>> thought I'd wait until other folks had a chance to ensure I didn't munge
>>>> stuff!
>>>>
>>>> As for getting documentation into their respective project sources, I'm
>>>> thinking of one of the following:
>>>>
>>>> 1. svn hook to copy the MarkDown docs *to* their respective location
>>>> *from* the current 'ASF-CMS' (vice ;-)
>>>> 2. svn hook to copy the MarkDown docs *to* the current 'ASF-CMS' *from*
>>>> their respective location (versa ;-)
>>>>
>>>> I suspect the desired approach would be #2, but the ASF-CMS system is
>>>> geared toward editing the docs in ASF-CMS, which would make #1 easier.
>>>>
>>>> Another possibility would be to somehow create a system to copy the
>>>> rendered HTML output to the repo…
>>>>
>>>> Thoughts? Preferences?
>>>>
>>>
>>> My preference is #2, i.e., to keep the doc sources in the same repositories
>>> as their non-doc sources.
>>
>> Figures that would be the preference… ;-)
>>
>> I suspect Option #1 be easiest to maintain (and implement). I imagine it working
this way:
>>
>> a. Edit the files/pages directly from within the CMS as is currently the case
>>      * no change to current web site/documentation editing on the ASF-CMS
>> b. commit the change to see it in STAGING
>>      * an SVN hook would need to be created, which copies site changes to the appropriate
local repository (FOP, Batik or Commons)
>> c. Check your changes on Staging
>> d. publish the site to see the changes on PRODUCTION
>>
>> Migrating to Option #2 would mean modifying how ASF-CMS works, and we wouldn't be
able to edit using the ASF-CMS user-interface.
>>
>>> I have to wonder what other projects are doing
>>> about this?
>>
>> From what I can tell, most of the others are either Top-Level Projects (TLPs like
Apache XML Project, which hosts retired projects Crimson & Xindice and which gave birth
to XML Graphics, and from whence Xerces & Xalan were born), or they're still using a combination
of Forrest and/or Maven[2] (e.g., Apache Web Services Project).
>>
>> [1] Apache XML Project
>> http://xml.apache.org
>>
>> [2]
>> http://ws.apache.org


Vincent

---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@xmlgraphics.apache.org
For additional commands, e-mail: general-help@xmlgraphics.apache.org


Mime
View raw message