joe_schaefer at yahoo
Apr 30, 2012, 10:02 AM
Views: 355
Permalink
|
Oh right, there are some superficial changes to make as well,
like ensuring there's a "trunk/" dir that contains everything
and that the sources are all within trunk/content".
----- Original Message -----
> From: Joe Schaefer <joe_schaefer [at] yahoo>
> To: "docs [at] httpd" <docs [at] httpd>
> Cc:
> Sent: Monday, April 30, 2012 12:46 PM
> Subject: Re: Proposal to move docs to Apache CMS
>
> ----- Original Message -----
>
>> From: Daniel Gruno <rumble [at] cord>
>> To: docs [at] httpd
>> Cc:
>> Sent: Monday, April 30, 2012 11:36 AM
>> Subject: Proposal to move docs to Apache CMS
>>
>> Hi all,
>>
>> Joe Schaefer has proposed that we move our documentation to the Apache
>> CMS(?) system (or at least try it out with a copy of trunk). From what I
>> have gathered with my discussion with Joe, this move would allow for
>> certain different ways of managing our documentation:
>>
>> 1) We can continue to commit XML files to SVN as we do now, but the
>> rebuilding could be managed by the CMS system, so we wouldn't have to
>> rebuild everything ourselves and then commit a heap of files for every
>> small edit we do. I am not aware of what would happen if someone commits
>> invalid XML though, but Joe should be on this mailing list, so if you
>> could, please do tell how that would be handled.
>
> The CMS relies on the build system to report errors thru its exit status.
> So if invalid XML is properly reported by the existing build system, the
> build will fail and the follow-on buildbot staging commit won't happen.
> The bug will need to be corrected before any further changes can be published.
>
>> 2) We can update/edit the XML files through an online XML editor
>> (presumably through cms.a.o?), and the resulting changes in the XHTML
>> will be automatically rebuilt by the server. This could ease up
>> situations where you have to make a minor modification, but don't have
>> all your SVN tools and repos at hand.
>>
>> This would, no doubt, be a big change in the way we work, and it would
>> also require that we convert our existing documents to utf-8 format, but
>> I do see some clear advantages in this proposal, thus I'm sending it to
>> this list.
>>
>> Any thoughts, ideas, comments?
>
> I've looked over the docs trees to see what needs to happen before this
> could actually work in practice. Besides migrating the sources to utf-8,
> there are a few other items that will need to be dealt with:
>
> 1) the build system will need to take a run-time argument to change the
> location of the build results to an arbitrary directory. IOW the build
> artifacts will go to a different (configurable) directory than the sources.
> The CMS will commit the build results back to svn, and the publication process
> is based on things being in svn, so you will be able to checkout/tag/whatever
> the live tree for release purposes.
>
> 2) the source documents themselves will need to be renamed from foo.xml.$lang to
> foo.$lang.xml and the build will need to preserve this rename- it is important
> to the CMS that the .xml/.html extension is in the final position.
>
> 3) the CMS will need some tweaking to get the redirect code to DTRT for
> the docs trees.
>
> Otherwise that should cover the required changes.
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docs-unsubscribe [at] httpd
> For additional commands, e-mail: docs-help [at] httpd
>
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe [at] httpd
For additional commands, e-mail: docs-help [at] httpd
|
