Login | Register For Free | Help
Search for: (Advanced)

Mailing List Archive: Apache: Docs

Proposal to move docs to Apache CMS

 

 

First page Previous page 1 2 Next page Last page  View All Apache docs RSS feed   Index | Next | Previous | View Threaded


rumble at cord

Apr 30, 2012, 8:36 AM

Post #1 of 46 (1248 views)
Permalink
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.

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?

With regards,
Daniel.

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe [at] httpd
For additional commands, e-mail: docs-help [at] httpd


rbowen at rcbowen

Apr 30, 2012, 8:46 AM

Post #2 of 46 (1219 views)
Permalink
Re: Proposal to move docs to Apache CMS [In reply to]

On Apr 30, 2012, at 11:36 AM, Daniel Gruno wrote:

> 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.
>
> 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?


Thanks for heading this up. I talked with Joe about this years ago, but then never followed up on it.

My biggest question is whether it would require that we rewrite our XML, or if the existing XML is already in the right DTD?

--
Rich Bowen
rbowen [at] rcbowen :: @rbowen
rbowen [at] apache


mads at toftum

Apr 30, 2012, 9:02 AM

Post #3 of 46 (1229 views)
Permalink
Re: Proposal to move docs to Apache CMS [In reply to]

On Mon, Apr 30, 2012 at 05:36:29PM +0200, Daniel Gruno wrote:
> 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:
>
We're already producing the docs in final form and will need to do so as
long as we distribute usable docs with httpd. Hence there's really no
need to get the CMS involved. All we need is for checkouts of the right
bits of svn, no more, no less. Hooking up with svnpubsub most likely
makes sense. As for the rest of the site, the parts that aren't in the
manual, that's another story which probably belongs on dev@ rather than
here.

vh

Mads Toftum
--
http://soulfood.dk

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe [at] httpd
For additional commands, e-mail: docs-help [at] httpd


rbowen at rcbowen

Apr 30, 2012, 9:21 AM

Post #4 of 46 (1224 views)
Permalink
Re: Proposal to move docs to Apache CMS [In reply to]

On Apr 30, 2012, at 11:46 AM, Rich Bowen wrote:

>
> Thanks for heading this up. I talked with Joe about this years ago, but then never followed up on it.
>
> My biggest question is whether it would require that we rewrite our XML, or if the existing XML is already in the right DTD?
>



Hmm. I think I misread. are we talking about the website, or the product documentation?

The former, I can see an advantage to, but the latter I might take some convincing. We ship those docs with the product, so maintaining them in the CMS might not be the best service to our users.
--
Rich Bowen
rbowen [at] rcbowen :: @rbowen
rbowen [at] apache


joe_schaefer at yahoo

Apr 30, 2012, 9:46 AM

Post #5 of 46 (1226 views)
Permalink
Re: Proposal to move docs to Apache CMS [In reply to]

----- 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


sf at sfritsch

Apr 30, 2012, 9:48 AM

Post #6 of 46 (1224 views)
Permalink
Re: Proposal to move docs to Apache CMS [In reply to]

On Monday 30 April 2012, Rich Bowen wrote:
> Hmm. I think I misread. are we talking about the website, or the
> product documentation?
>
> The former, I can see an advantage to, but the latter I might take
> some convincing. We ship those docs with the product, so
> maintaining them in the CMS might not be the best service to our
> users. --

FWIW, the documentation shipped in the tarball would greatly benefit
from not using typemaps and content negotiation. The current format is
a PITA to view directly with a browser. And if you have a problem that
makes httpd fail to start, you are out of luck. Unless you can access
the copy on httpd.apache.org - but why then ship the docs in the
tarball in the first place?

In Debian, we already ship the docs in a standalone format (converted
with a perl search and replace script). But having some XSLT magic
that does the right thing would be much nicer.

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe [at] httpd
For additional commands, e-mail: docs-help [at] httpd


joe_schaefer at yahoo

Apr 30, 2012, 10:02 AM

Post #7 of 46 (1220 views)
Permalink
Re: Proposal to move docs to Apache CMS [In reply to]

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


nd at perlig

May 1, 2012, 10:12 AM

Post #8 of 46 (1213 views)
Permalink
Re: Proposal to move docs to Apache CMS [In reply to]

I don't know much about the CMS->SVN system. We use the revision numbers
heavily to track translation age. Does this continue to work?

nd

* Joe Schaefer wrote:

> ----- 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



--
Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook.
Ook! Ook? Ook. Ook? Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook. Ook.
Ook. Ook. Ook. Ook. Ook? Ook. Ook! Ook! Ook? Ook! Ook. Ook? Ook. Ook.
Ook. Ook. Ook. Ook. Ook! Ook. Ook! Ook! Ook! Ook! Ook! Ook.

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe [at] httpd
For additional commands, e-mail: docs-help [at] httpd


nd at perlig

May 1, 2012, 10:14 AM

Post #9 of 46 (1217 views)
Permalink
Re: Proposal to move docs to Apache CMS [In reply to]

* Stefan Fritsch wrote:

> On Monday 30 April 2012, Rich Bowen wrote:
> > Hmm. I think I misread. are we talking about the website, or the
> > product documentation?
> >
> > The former, I can see an advantage to, but the latter I might take
> > some convincing. We ship those docs with the product, so
> > maintaining them in the CMS might not be the best service to our
> > users. --
>
> FWIW, the documentation shipped in the tarball would greatly benefit
> from not using typemaps and content negotiation.

Well. it's provided as an example, too (how to achive that). Maybe we should
more promote the language-tarballs available in the download section?

nd
--
Winnetous Erbe: <http://pub.perlig.de/books.html#apache2>

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe [at] httpd
For additional commands, e-mail: docs-help [at] httpd


nd at perlig

May 1, 2012, 10:15 AM

Post #10 of 46 (1216 views)
Permalink
Re: Proposal to move docs to Apache CMS [In reply to]

* Rich Bowen wrote:

> are we talking about the website, or the product documentation?
>
> The former, I can see an advantage to, but the latter I might take some
> convincing.

yep. I'm not.

nd
--
sub the($){+shift} sub answer (){ord q
[* It is always 42! *] }
print the answer
# André Malo # http://pub.perlig.de/ #

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe [at] httpd
For additional commands, e-mail: docs-help [at] httpd


noirin at apache

May 2, 2012, 2:00 PM

Post #11 of 46 (1220 views)
Permalink
Re: Proposal to move docs to Apache CMS [In reply to]

On Mon, Apr 30, 2012 at 8:36 AM, Daniel Gruno <rumble [at] cord> wrote:
> 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:

I, for one, welcome our new CMS overlords :-)

Seriously though, the hassle of checking out the docs tree, finding
the build tree, remembering where I'm meant to check that out to, ...
is, well, a hassle.

I'd love to see stuff moved into the CMS, or to have some equivalently
automated way of doing stuff.

Noirin

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe [at] httpd
For additional commands, e-mail: docs-help [at] httpd


nd at perlig

May 2, 2012, 2:40 PM

Post #12 of 46 (1215 views)
Permalink
Re: Proposal to move docs to Apache CMS [In reply to]

* Nóirín Plunkett wrote:

> On Mon, Apr 30, 2012 at 8:36 AM, Daniel Gruno <rumble [at] cord> wrote:
> > 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:
>
> I, for one, welcome our new CMS overlords :-)
>
> Seriously though, the hassle of checking out the docs tree, finding
> the build tree, remembering where I'm meant to check that out to, ...
> is, well, a hassle.

Well. There's not effort needed for *that* hassle. It's documented on the
docs-project pages (since ever). [1] [2]

http://httpd.apache.org/docs-project/docsformat.html

OTOH, remembering where the CMS is and how it works, would actually be a
hassle for *me* (and I'd guess, various developers trying to write
documentation while writing code, too [which should be encouraged!]).

More thoughts on this (unsorted):

- Also it's a nice thing to check in documentation together with code. From
time to time patches arrive that way. In fact, I'd rather support more of
those.

- Oh, patches. How does the CMS deal with those in general? Do I need to
apply them manually then in a browser window?

- Which leads to the next point: I've never used the CMS. How does it play
together with my own editor?

- How does the CMS play along with the other build targets (CHM, tarball). I
guess, it does not at all (CHM needs windows in very specific
configurations). So we still need a separate build system then?

- How does the CMS handle the build output? (e.g. ./build.sh de emits the
outdated de-translations at the end)

nd

[1] *Sigh* I'm wondering, why so many people here don't know about OUR
docs-project pages.

[2] Not everybody needs to run the build system (some people don't even have
java on their box). Someone else will run it then at the next
opportunity. In fact, it's encouraged that you run it only on languages
you understand enough.

--
If God intended people to be naked, they would be born that way.
-- Oscar Wilde

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe [at] httpd
For additional commands, e-mail: docs-help [at] httpd


pctony at apache

May 2, 2012, 2:46 PM

Post #13 of 46 (1216 views)
Permalink
Re: Proposal to move docs to Apache CMS [In reply to]

André Malo wrote on Wed, May 02, 2012 at 11:40:22PM +0200:

> OTOH, remembering where the CMS is and how it works, would actually be a
> hassle for *me* (and I'd guess, various developers trying to write
> documentation while writing code, too [which should be encouraged!]).

Actually, no. You browse to the page you want to edit, then in your bookmarks you have a little bookmarklet "javascript:void(location.href='https://cms.apache.org/redirect?uri='+escape(location.href))" that essentially take you through to a location with a WYSIWYG editor, you commit your change and i goes into staging (after being built), you can then review your change(s) at httpd.staging.a.o/path/to/docs if it looks clean, you hit publish. End of.


--

Cheers,
Tony


---------------------------------------
Tony Stevenson

tony [at] pc-tony // pctony [at] apache
tony [at] caret

http://blog.pc-tony.com

GPG - 1024D/51047D66
--------------------------------------"
Attachments: signature.asc (0.23 KB)


noirin at apache

May 2, 2012, 2:50 PM

Post #14 of 46 (1210 views)
Permalink
Re: Proposal to move docs to Apache CMS [In reply to]

On Wed, May 2, 2012 at 2:40 PM, André Malo <nd [at] perlig> wrote:
> * Nóirín Plunkett wrote:
>>
>> I, for one, welcome our new CMS overlords :-)
>>
>> Seriously though, the hassle of checking out the docs tree, finding
>> the build tree, remembering where I'm meant to check that out to, ...
>> is, well, a hassle.
>
> Well. There's not effort needed for *that* hassle. It's documented on the
> docs-project pages (since ever). [1] [2]
>
> http://httpd.apache.org/docs-project/docsformat.html

Except that that page is a nightmare to find, and only tells me what
to do after I'm already on step three.

It might not seem like much hassle to you, but it's enough to blow
away my motivation to fix anything.

> OTOH, remembering where the CMS is and how it works, would actually be a
> hassle for *me* (and I'd guess, various developers trying to write
> documentation while writing code, too [which should be encouraged!]).

For me, "the CMS" is just a bookmarklet in my browser. And when I'm on
a new machine, or I've forgotten how it works, I search for apache cms
and a set of reasonably clear instructions pops up as the third result
in Google.

> - Also it's a nice thing to check in documentation together with code. From
>  time to time patches arrive that way. In fact, I'd rather support more of
>  those.

Agreed.

> - Oh, patches. How does the CMS deal with those in general? Do I need to
>  apply them manually then in a browser window?
>
> - Which leads to the next point: I've never used the CMS. How does it play
>  together with my own editor?
>
> - How does the CMS play along with the other build targets (CHM, tarball). I
>  guess, it does not at all (CHM needs windows in very specific
>  configurations). So we still need a separate build system then?
>
> - How does the CMS handle the build output? (e.g. ./build.sh de emits the
>  outdated de-translations at the end)

I don't know the answers to these questions, and I certainly don't
assume that the CMS is perfect. Moving to the CMS will almost
certainly require changes in workflow, and may well make things harder
for some people. But our current system effectively excludes other
people. That may be ok with y'all, in which case I'll go back to
lurking, but I'd rather be knowingly excluded than silently :-)

> [1] *Sigh* I'm wondering, why so many people here don't know about OUR
>    docs-project pages.

They're hard to find. Even when I know they exist, I can't find them.

> [2] Not everybody needs to run the build system (some people don't even have
>    java on their box). Someone else will run it then at the next
>    opportunity. In fact, it's encouraged that you run it only on languages
>    you understand enough.

I've broken the build with poor XML more than once, so I don't like to
check in anything I haven't built.

N

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe [at] httpd
For additional commands, e-mail: docs-help [at] httpd


rumble at cord

May 2, 2012, 2:53 PM

Post #15 of 46 (1216 views)
Permalink
Re: Proposal to move docs to Apache CMS [In reply to]

On 02-05-2012 23:40, André Malo wrote:
>
> More thoughts on this (unsorted):
>
> - Also it's a nice thing to check in documentation together with code. From
> time to time patches arrive that way. In fact, I'd rather support more of
> those.
>
> - Oh, patches. How does the CMS deal with those in general? Do I need to
> apply them manually then in a browser window?
>
> - Which leads to the next point: I've never used the CMS. How does it play
> together with my own editor?
>
> - How does the CMS play along with the other build targets (CHM, tarball). I
> guess, it does not at all (CHM needs windows in very specific
> configurations). So we still need a separate build system then?
>
> - How does the CMS handle the build output? (e.g. ./build.sh de emits the
> outdated de-translations at the end)
>
> nd
>
> [1] *Sigh* I'm wondering, why so many people here don't know about OUR
> docs-project pages.
>
> [2] Not everybody needs to run the build system (some people don't even have
> java on their box). Someone else will run it then at the next
> opportunity. In fact, it's encouraged that you run it only on languages
> you understand enough.
>

I do have some similar concerns that I would like to get addressed
before I can form an actual opinion about moving to a CMS system:

1) What happens if (or rather when) a build fails? Will there be a
notification of sorts to some mailing list? As I recall, in our current
build system, documents are first deleted, then attempted rebuilt, thus
when a build fails, it leaves us without the .html.en page - would that
simply make the page 404'ed on our site, and subsequently, would it
delete it from the svn repo?

2) How is an online edit recorded? When I edit something online, does it
register as an SVN commit what I do, or does it just magically update
itself out of thin air? And what about rebuilds, would they be counted
as a separate commit or how would that fit in? And can I add a log entry
to my edit?

What I guess it boils down to is this: I'd really, really like for some
"trunk-trunk" where we could see how this system actually works, before
I can make up my mind. Would this be possible to do?

And finally, slightly off-topic, I would like to thank André for his
efforts in rebuilding and fixing up props when the rest of us
narrow-minded people neglect to do so - your attention to details is
commendable. Maybe, similar to the proposed clone_drbacchus() function,
we can add one for you as well :) (get working on the code already, wrowe!)

With regards,
Daniel.

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe [at] httpd
For additional commands, e-mail: docs-help [at] httpd


pctony at apache

May 2, 2012, 2:55 PM

Post #16 of 46 (1216 views)
Permalink
Re: Proposal to move docs to Apache CMS [In reply to]

Nóirín Plunkett wrote on Wed, May 02, 2012 at 02:50:21PM -0700:
> On Wed, May 2, 2012 at 2:40 PM, André Malo <nd [at] perlig> wrote:
> > * Nóirín Plunkett wrote:
> >>
> >> I, for one, welcome our new CMS overlords :-)
> >>
> >> Seriously though, the hassle of checking out the docs tree, finding
> >> the build tree, remembering where I'm meant to check that out to, ...
> >> is, well, a hassle.
> >
> > Well. There's not effort needed for *that* hassle. It's documented on the
> > docs-project pages (since ever). [1] [2]
> >
> > http://httpd.apache.org/docs-project/docsformat.html
>
> Except that that page is a nightmare to find, and only tells me what
> to do after I'm already on step three.
>
> It might not seem like much hassle to you, but it's enough to blow
> away my motivation to fix anything.
>
> > OTOH, remembering where the CMS is and how it works, would actually be a
> > hassle for *me* (and I'd guess, various developers trying to write
> > documentation while writing code, too [which should be encouraged!]).
>
> For me, "the CMS" is just a bookmarklet in my browser. And when I'm on
> a new machine, or I've forgotten how it works, I search for apache cms
> and a set of reasonably clear instructions pops up as the third result
> in Google.
>
> > - Also it's a nice thing to check in documentation together with code. From
> >  time to time patches arrive that way. In fact, I'd rather support more of
> >  those.
>
> Agreed.
>
> > - Oh, patches. How does the CMS deal with those in general? Do I need to
> >  apply them manually then in a browser window?

No, you can apply them directly against the svn tree used to build the site. The CMS is NOT a browser only option.

> > - Which leads to the next point: I've never used the CMS. How does it play
> >  together with my own editor?

The CMS is built entorely around SVN. If you check out the tree, edit locally, and commit, you can goto the staging site and see your changes (as soon as buildbot has run the build task).

> > - How does the CMS play along with the other build targets (CHM, tarball). I
> >  guess, it does not at all (CHM needs windows in very specific
> >  configurations). So we still need a separate build system then?
> >
> > - How does the CMS handle the build output? (e.g. ./build.sh de emits the
> >  outdated de-translations at the end)
>
> I don't know the answers to these questions, and I certainly don't
> assume that the CMS is perfect. Moving to the CMS will almost
> certainly require changes in workflow, and may well make things harder
> for some people. But our current system effectively excludes other
> people. That may be ok with y'all, in which case I'll go back to
> lurking, but I'd rather be knowingly excluded than silently :-)
>
> > [1] *Sigh* I'm wondering, why so many people here don't know about OUR
> >    docs-project pages.
>
> They're hard to find. Even when I know they exist, I can't find them.
>
> > [2] Not everybody needs to run the build system (some people don't even have
> >    java on their box). Someone else will run it then at the next
> >    opportunity. In fact, it's encouraged that you run it only on languages
> >    you understand enough.
>
> I've broken the build with poor XML more than once, so I don't like to
> check in anything I haven't built.
>
> N
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docs-unsubscribe [at] httpd
> For additional commands, e-mail: docs-help [at] httpd
>

--

Cheers,
Tony


---------------------------------------
Tony Stevenson

tony [at] pc-tony // pctony [at] apache
tony [at] caret

http://blog.pc-tony.com

GPG - 1024D/51047D66
--------------------------------------"
Attachments: signature.asc (0.23 KB)


pctony at apache

May 2, 2012, 2:58 PM

Post #17 of 46 (1214 views)
Permalink
Re: Proposal to move docs to Apache CMS [In reply to]

Daniel Gruno wrote on Wed, May 02, 2012 at 11:53:48PM +0200:
> On 02-05-2012 23:40, André Malo wrote:
> >
> > More thoughts on this (unsorted):
> >
> > - Also it's a nice thing to check in documentation together with code. From
> > time to time patches arrive that way. In fact, I'd rather support more of
> > those.
> >
> > - Oh, patches. How does the CMS deal with those in general? Do I need to
> > apply them manually then in a browser window?
> >
> > - Which leads to the next point: I've never used the CMS. How does it play
> > together with my own editor?
> >
> > - How does the CMS play along with the other build targets (CHM, tarball). I
> > guess, it does not at all (CHM needs windows in very specific
> > configurations). So we still need a separate build system then?
> >
> > - How does the CMS handle the build output? (e.g. ./build.sh de emits the
> > outdated de-translations at the end)
> >
> > nd
> >
> > [1] *Sigh* I'm wondering, why so many people here don't know about OUR
> > docs-project pages.
> >
> > [2] Not everybody needs to run the build system (some people don't even have
> > java on their box). Someone else will run it then at the next
> > opportunity. In fact, it's encouraged that you run it only on languages
> > you understand enough.
> >
>
> I do have some similar concerns that I would like to get addressed
> before I can form an actual opinion about moving to a CMS system:
>
> 1) What happens if (or rather when) a build fails? Will there be a
> notification of sorts to some mailing list? As I recall, in our current
> build system, documents are first deleted, then attempted rebuilt, thus
> when a build fails, it leaves us without the .html.en page - would that
> simply make the page 404'ed on our site, and subsequently, would it
> delete it from the svn repo?

It is two stage. You first review in staging, if you "like what you see" - i.e. review the build, then you publish it. If you choose to do this without a review of the output, then clearly this is a risk you elect to take.

> 2) How is an online edit recorded? When I edit something online, does it
> register as an SVN commit what I do, or does it just magically update
> itself out of thin air? And what about rebuilds, would they be counted
> as a separate commit or how would that fit in? And can I add a log entry
> to my edit?

The whoel CMS is built around SVN, ultimately all changes are revisions, and ad such auditable, revertable etc. Please dont think of the CMS as a traditional browser only based tool. You *could* operate entirely in a shell if you so chose.

>
> What I guess it boils down to is this: I'd really, really like for some
> "trunk-trunk" where we could see how this system actually works, before
> I can make up my mind. Would this be possible to do?
>
> And finally, slightly off-topic, I would like to thank André for his
> efforts in rebuilding and fixing up props when the rest of us
> narrow-minded people neglect to do so - your attention to details is
> commendable. Maybe, similar to the proposed clone_drbacchus() function,
> we can add one for you as well :) (get working on the code already, wrowe!)
>
> With regards,
> Daniel.
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docs-unsubscribe [at] httpd
> For additional commands, e-mail: docs-help [at] httpd
>

--

Cheers,
Tony


---------------------------------------
Tony Stevenson

tony [at] pc-tony // pctony [at] apache
tony [at] caret

http://blog.pc-tony.com

GPG - 1024D/51047D66
--------------------------------------"
Attachments: signature.asc (0.23 KB)


nd at perlig

May 2, 2012, 3:07 PM

Post #18 of 46 (1212 views)
Permalink
Re: Proposal to move docs to Apache CMS [In reply to]

* Nóirín Plunkett wrote:

> > [1] *Sigh* I'm wondering, why so many people here don't know about OUR
> >    docs-project pages.
>
> They're hard to find. Even when I know they exist, I can't find them.

http://httpd.apache.org/ is always a good starting point. Then one navigates
on the left side to Subprojects/Docs. Done. "How to get Involved" is what
you're looking for. [1]

Sorry, if that's too hard.
But these are our pages. If you want to improve those, it's welcome, too.

nd

[1] as for googling about how it works:

https://www.google.com/search?hl=en&q=apache+docs+transformation
https://www.google.com/search?hl=en&q=httpd+docs+transformation
--
Flhacs wird im Usenet grundsätzlich alsfhc geschrieben. Schreibt man
lafhsc nicht slfach, so ist das schlichtweg hclafs. Hingegen darf man
rihctig ruhig rhitcgi schreiben, weil eine shcalfe Schreibweise bei
irhictg nicht als shflac angesehen wird. -- Hajo Pflüger in dnq

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe [at] httpd
For additional commands, e-mail: docs-help [at] httpd


noirin at apache

May 2, 2012, 3:13 PM

Post #19 of 46 (1212 views)
Permalink
Re: Proposal to move docs to Apache CMS [In reply to]

On Wed, May 2, 2012 at 3:07 PM, André Malo <nd [at] perlig> wrote:
> * Nóirín Plunkett wrote:
>
>> > [1] *Sigh* I'm wondering, why so many people here don't know about OUR
>> >    docs-project pages.
>>
>> They're hard to find. Even when I know they exist, I can't find them.
>
> http://httpd.apache.org/ is always a good starting point. Then one navigates
> on the left side to Subprojects/Docs. Done. "How to get Involved" is what
> you're looking for. [1]

Damn. Because this one looks at the bold "Documentation" link that's
above the fold, clicks there, keeps navigating on for a bit and can't
find what she wants. I'm glad that you're able to find them, but
Subprojects isn't a heading that makes me think "oh, yeah, that's how
I contribute" or even "oh, yeah, documentation", and when clicking on
"Documentation" has failed, the plain, below-the-fold "Docs" link is
not where I go.

> Sorry, if that's too hard.
> But these are our pages. If you want to improve those, it's welcome, too.

Frankly, given my limited time and energy, yes that is too hard to get
my contributions.

> [1] as for googling about how it works:
>
> https://www.google.com/search?hl=en&q=apache+docs+transformation
> https://www.google.com/search?hl=en&q=httpd+docs+transformation

"transformation" is not a word I would ever think to include in my
search. Maybe I'm just not who you want contributing to the docs?

Noirin

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe [at] httpd
For additional commands, e-mail: docs-help [at] httpd


pctony at apache

May 2, 2012, 3:18 PM

Post #20 of 46 (1215 views)
Permalink
Re: Proposal to move docs to Apache CMS [In reply to]

Nóirín Plunkett wrote on Wed, May 02, 2012 at 03:13:16PM -0700:
> On Wed, May 2, 2012 at 3:07 PM, André Malo <nd [at] perlig> wrote:
> > * Nóirín Plunkett wrote:
> >
> >> > [1] *Sigh* I'm wondering, why so many people here don't know about OUR
> >> >    docs-project pages.
> >>
> >> They're hard to find. Even when I know they exist, I can't find them.
> >
> > http://httpd.apache.org/ is always a good starting point. Then one navigates
> > on the left side to Subprojects/Docs. Done. "How to get Involved" is what
> > you're looking for. [1]
>
> Damn. Because this one looks at the bold "Documentation" link that's
> above the fold, clicks there, keeps navigating on for a bit and can't
> find what she wants. I'm glad that you're able to find them, but
> Subprojects isn't a heading that makes me think "oh, yeah, that's how
> I contribute" or even "oh, yeah, documentation", and when clicking on
> "Documentation" has failed, the plain, below-the-fold "Docs" link is
> not where I go.
>
> > Sorry, if that's too hard.
> > But these are our pages. If you want to improve those, it's welcome, too.
>
> Frankly, given my limited time and energy, yes that is too hard to get
> my contributions.

Agreed whole heartedly.

>
> > [1] as for googling about how it works:
> >
> > https://www.google.com/search?hl=en&q=apache+docs+transformation
> > https://www.google.com/search?hl=en&q=httpd+docs+transformation
>
> "transformation" is not a word I would ever think to include in my
> search. Maybe I'm just not who you want contributing to the docs?

No, you're exactly the kind of person we need. Someone who can spot an issue, quickly commit a change, review it and publish it. Setting up the whole docs build has always been a bug bear of mine too. Every time I change machine, I have to re-learn how to set it up. It's such a palava I don't bother anymore. Which has sadly led me to not committing much. It is such a barrier to entry, a pointless one at that when we have something that is so much more efficient and effective.


--

Cheers,
Tony


---------------------------------------
Tony Stevenson

tony [at] pc-tony // pctony [at] apache
tony [at] caret

http://blog.pc-tony.com

GPG - 1024D/51047D66
--------------------------------------"
Attachments: signature.asc (0.23 KB)


rumble at cord

May 2, 2012, 3:28 PM

Post #21 of 46 (1211 views)
Permalink
Re: Proposal to move docs to Apache CMS [In reply to]

On 03-05-2012 00:13, Nóirín Plunkett wrote:
> Damn. Because this one looks at the bold "Documentation" link that's
> above the fold, clicks there, keeps navigating on for a bit and can't
> find what she wants. I'm glad that you're able to find them, but
> Subprojects isn't a heading that makes me think "oh, yeah, that's how
> I contribute" or even "oh, yeah, documentation", and when clicking on
> "Documentation" has failed, the plain, below-the-fold "Docs" link is
> not where I go.
> ......
I think a more direct link to how to get involved as a documentation
contributor might be in order, if that's what we wanna aim at.
"Developer info" doesn't strike me as being related to documentation,
but maybe that's just how my mind associates things.

> "transformation" is not a word I would ever think to include in my
> search. Maybe I'm just not who you want contributing to the docs?
>
> Noirin
>

I had to be nannied and poked and prodded by Rich myself in order to
figure out how the system worked, and the notion alone of having to work
with SVN, committing changes, updating repos whenever someone farted and
so forth made me a bit scared of the whole system at first, so I fully
understand and share your frustration in how the process is set up. From
what I can gather, with a CMS approach, we could basically tell people
"Hey, go to this address and edit the friggin page like a Wiki", which
in my opinion would encourage far better than "hey, install svn, check
out three or four repos on each of your computers, commit the changes,
rebuild the entire docs site, remember to rebuild the rebuild in case
the revision changed etc etc"

With regards,
Daniel.


---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe [at] httpd
For additional commands, e-mail: docs-help [at] httpd


rumble at cord

May 2, 2012, 3:52 PM

Post #22 of 46 (1216 views)
Permalink
Re: Proposal to move docs to Apache CMS [In reply to]

Clean slate here, because this is just some free thoughts:

I am for moving both the site and the documentation to the CMS system if
it indeed works as Tony explained. I'm also in favor of Noirin's
suggestion about making how to contribute to documentation clearer.

My train of thoughts as I start from the front page is:

1) Where can I contribute to documentation? I don't see it
2) I'm a newbie, what or who is SVN?
3) How do I write a patch or check out a repo? (I see a LOT of bugs on
the docs bugzilla where people obviously don't know what a patch is)
4) Okay, I wrote something - why doesn't it show? I need to rebuild?
5) What's XSLT, I just wanted to help with a translation?!
6) Will everything blow up when I commit something?
7) I can't make Java or Perl or insert-process-here work!

Apart from question 2, I had to ask all of those questions when I
started as a contributor and moved up as a committer, and if it weren't
for my enthusiasm, I would've stayed as a contributor and just mailed a
few patches here and there at best. So I think what Noirin pointed out
is actually something vital that's preventing people from contributing
more to our documentation that they could, adding more work for the rest
of us to do. I'm happy to do as much work as I can, but there have been
quite a few times where I have wanted to just tell Mr. X-y-z "Do A, B
and C and you're done in 2 minutes". And I think that using a CMS
system, we could at least cut down on all the steps that has to be taken
for people to add/edit our stuff.

Yes, they would still have to be committers or whatever, but the mere
process would be easy to overlook and friendly to new people, and I
think that alone would not alone make it less frightening to newcomers,
but also make it easier for us to encourage people to become
contributors or committers.

I hope half of that at least made sense.

With regards,
Daniel.

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe [at] httpd
For additional commands, e-mail: docs-help [at] httpd


rbowen at rcbowen

May 2, 2012, 5:34 PM

Post #23 of 46 (1211 views)
Permalink
Re: Proposal to move docs to Apache CMS [In reply to]

> >
> > http://httpd.apache.org/docs-project/docsformat.html
>
> Except that that page is a nightmare to find, and only tells me what
> to do after I'm already on step three.
>
> It might not seem like much hassle to you, but it's enough to blow
> away my motivation to fix anything.
>

For whatever it's worth (noting much yet) Humbedooh and I have been working
to improve that page and others in that general vicinity over the last two
weeks. Hopefully it's better now and will be even better next week.

I share Andre's concerns, mostly, I'm sure, due to ignorance about how
this all works. But I'm willing to give it a try. Whats the procedure?


rbowen at rcbowen

May 2, 2012, 5:40 PM

Post #24 of 46 (1216 views)
Permalink
Re: Proposal to move docs to Apache CMS [In reply to]

> Damn. Because this one looks at the bold "Documentation" link that's
> above the fold, clicks there, keeps navigating on for a bit and can't
> find what she wants. I'm glad that you're able to find them, but
> Subprojects isn't a heading that makes me think "oh, yeah, that's how
> I contribute" or even "oh, yeah, documentation", and when clicking on
> "Documentation" has failed, the plain, below-the-fold "Docs" link is
> not where I go.
>

In the trunk version of this stuff there are links to "help us with the
docs" from all over the place. Tomorrow there will be links on the live
site. I agree, we make it too hard to find. I'll fix that.


rbowen at rcbowen

May 2, 2012, 5:46 PM

Post #25 of 46 (1224 views)
Permalink
Re: Proposal to move docs to Apache CMS [In reply to]

On 2012 5 2 18:52, "Daniel Gruno" <rumble [at] cord> wrote:
>
> Clean slate here, because this is just some free thoughts:
>
> I am for moving both the site and the documentation to the CMS system if
> it indeed works as Tony explained. I'm also in favor of Noirin's
> suggestion about making how to contribute to documentation clearer

Not that, as mentioned elsewhere, these changes are in the process of being
made and will be made tomorrow. But if the process is too hard, all the
documentation in the world doesn't help.
>
> My train of thoughts as I start from the front page is:
>
> 1) Where can I contribute to documentation? I don't see it
> 2) I'm a newbie, what or who is SVN?
> 3) How do I write a patch or check out a repo? (I see a LOT of bugs on
> the docs bugzilla where people obviously don't know what a patch is)
> 4) Okay, I wrote something - why doesn't it show? I need to rebuild?
> 5) What's XSLT, I just wanted to help with a translation?!
> 6) Will everything blow up when I commit something?
> 7) I can't make Java or Perl or insert-process-here work!
>

Let's talk more tomorrow about writing exactly those docs.

But, yeah, I'd like to see what's involved in getting a demo going in the
cms. Lets do that.

First page Previous page 1 2 Next page Last page  View All Apache docs RSS feed   Index | Next | Previous | View Threaded
 
 


Interested in having your list archived? Contact Gossamer Threads
 
  Web Applications & Managed Hosting Powered by Gossamer Threads Inc.