xmlgraphics-general mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Pascal Sancho <psancho....@gmail.com>
Subject Re: documentation!???
Date Mon, 11 Feb 2013 08:10:47 GMT
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?

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
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: general-unsubscribe@xmlgraphics.apache.org
> For additional commands, e-mail: general-help@xmlgraphics.apache.org
>



-- 
pascal

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


Mime
View raw message