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


joe_schaefer at yahoo

May 2, 2012, 5:49 PM

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

I already told everyone what changes are
required for the CMS to work properly
with the docs tree, starting with utf-8.

Some changes are trivial, others are not.




>________________________________
> From: Rich Bowen <rbowen [at] rcbowen>
>To: docs [at] httpd
>Sent: Wednesday, May 2, 2012 8:46 PM
>Subject: Re: Proposal to move docs to Apache CMS
>
>
>
>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.
>
>
>


rbowen at rcbowen

May 2, 2012, 5:56 PM

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

On 2012 5 2 20:49, "Joe Schaefer" <joe_schaefer [at] yahoo> wrote:
>
> I already told everyone what changes are
> required for the CMS to work properly
> with the docs tree, starting with utf-8.
> Some changes are trivial, others are not.
>

Yes, you did, and its going to take me a bit to translate into specific
actions we need to take. I'm not sure I actually know how to do the things
you stated. I guess I'll find out in the morning.


nd at perlig

May 3, 2012, 12:05 AM

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

On Wednesday 02 May 2012 23:50:21 Nóirín Plunkett wrote:

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

Oh, forgot to reply to this. We've taken care of that right from the
beginning. The docs structure is self-contained. You can open the XML file in
any xslt-capable webbrowser (e.g. firefox). It will transform it for you (or
bail out if the XML is not wellformed).

Thatswhy you don't need the build system, escpecially for minimal changes.

nd

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


nd at perlig

May 3, 2012, 12:08 AM

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

On Thursday 03 May 2012 02:56:12 Rich Bowen wrote:
> On 2012 5 2 20:49, "Joe Schaefer" <joe_schaefer [at] yahoo> wrote:
> > I already told everyone what changes are
> > required for the CMS to work properly
> > with the docs tree, starting with utf-8.
> > Some changes are trivial, others are not.
>
> Yes, you did, and its going to take me a bit to translate into specific
> actions we need to take. I'm not sure I actually know how to do the things
> you stated. I guess I'll find out in the morning.


Changing the directory structure will require changes in the XSLT, too. That's
a big task. Also I don't like very much the prospect of changing more or less
every document in order to simply add another edit frontend.

nd

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


nd at perlig

May 3, 2012, 12:20 AM

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

On Thursday 03 May 2012 00:52:02 Daniel Gruno 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.
>
> 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.

Maybe I've missed it (quite possible), but did you ask here on the ML? I've
heard a lot about IRC (or other) talks lately about this and that. Things
should happen on the list - and not only the conclusions. Maybe we already
would have a better self-documentation by now.

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

Yes. Answering those questions above would be a big help. Beside the technical
answers we should also point the people to the mailing list to ask their
questions.
However, I'm also inclined to say, that if we're not able to use our own
self-documentation properly, we're doing something very wrong. And it's not
very much. Just a few pages. No offense to anyone, but I'm pretty frustrated
by the "I would contribute, but I don't bother to get some community context"
attitude floating around.

nd

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


nd at perlig

May 3, 2012, 12:26 AM

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

On Thursday 03 May 2012 00:13:16 Nóirín Plunkett wrote:

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

I wouldn't make that a function of what words you type in at google. Maybe
just telling what you're *actually* googling would be more helpful ;-)

https://www.google.com/search?hl=en&q=apache+docs+build works fine, too.
That's what I'd actually try in the first place.

nd

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


rumble at cord

May 3, 2012, 1:38 AM

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

On 03-05-2012 09:20, André Malo wrote:
> Maybe I've missed it (quite possible), but did you ask here on the ML? I've
> heard a lot about IRC (or other) talks lately about this and that. Things
> should happen on the list - and not only the conclusions. Maybe we already
> would have a better self-documentation by now.
>
Last night was late, so sorry if I started rambling - I tend to do that.

I initially got recruited over IRC, so that's where I have been prone to
ask quick questions about the process of committing docs. Yes, some of
us have been very bad at having discussions off-list, and we really
should improve on that. I must admit, I wasn't fully aware of how things
proceeded, and I wasn't really being nudged by others to start
discussions on the mailing list, but pointing fingers at who did what
doesn't do much for me, so I think it's better to just admit that we
didn't do our due diligence and that the mailing list should be the
preferred place for actual discussions, as it is with this one.

This is also why I insisted, on the topic of highlighting, that people
start replying on the mailing list instead, because I was starting to
get very confused about how things really worked. I'm a new guy to all
of this, and I just in the direction people point at.

> Yes. Answering those questions above would be a big help. Beside the technical
> answers we should also point the people to the mailing list to ask their
> questions.
> However, I'm also inclined to say, that if we're not able to use our own
> self-documentation properly, we're doing something very wrong. And it's not
> very much. Just a few pages. No offense to anyone, but I'm pretty frustrated
> by the "I would contribute, but I don't bother to get some community context"
> attitude floating around.

Perhaps we should emphasize this more in our documentation on how to
contribute, maybe either make up a small guide on which steps are taken
when you contribute or discuss (bullet-point style), or maybe we just
need to change some wordings to make it easier to find (or maybe I'm
just being ignorant). I know (now) that we have documentation on how to
commit, but, just as I see frequently on #httpd on freenode, when asked
to read something, the human mind doesn't always pay a whole lot of
attention to the details, especially if it's "hidden" inside a long
document with a lot of irrelevant information before the bits one needs,
so this should really be emphasized and checked up on when letting new
contributors/committers into the fold.

What I would've liked is some simple guide that says:

- Great, you found a bug/error!
- Check out our repository (here's how to do that)
- Edit the XML file that has the error/missing feature
- Optionally use our build tool to check out the new version of the doc
- use svn diff > something.patch or whichever tool you like
- If you're not a committer, send it to our mailing list docs [at] h with
a description of what changed and why.
- If you're a committer, upload it to trunk, notify mailing list if it's
a major change, let people review it, and if okay, backport it to 2.4.
- Quick questions on IRC or other off-list methods is fine, but any
actual discussion and review must take place on the mailing list.

With regards, however off-topic this reply may be,
Daniel.

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


i.galic at brainsware

May 3, 2012, 6:37 AM

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

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

A lot of these questions I'd like to have answered for Traffic Server
as well. I guess the best way is if I just help you with it ;)

i

--
Igor Galić

Tel: +43 (0) 664 886 22 883
Mail: i.galic [at] brainsware
URL: http://brainsware.org/
GPG: 6880 4155 74BD FD7C B515 2EA5 4B1D 9E08 A097 C9AE


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


rbowen at rcbowen

May 3, 2012, 6:38 AM

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

On May 3, 2012, at 3:20 AM, André Malo wrote:

> Yes. Answering those questions above would be a big help. Beside the technical
> answers we should also point the people to the mailing list to ask their
> questions.
> However, I'm also inclined to say, that if we're not able to use our own
> self-documentation properly, we're doing something very wrong. And it's not
> very much. Just a few pages. No offense to anyone, but I'm pretty frustrated
> by the "I would contribute, but I don't bother to get some community context"
> attitude floating around.


Oh, I don't know about that. I think that we should indeed lower the bar to contributing to the docs. I don't think it should be a requirement to learn about XML, XSLT, SVN, or Ant in order to say "wouldn't that sentence flow better if you said ..." Besides which, the "community context" should be one of welcoming, not one of "go read the documentation for our documentation before you can tell us we misspelled peony."

I've been contributing to the documentation for 12 years, and I still find http://httpd.apache.org/docs-project/ to be ... well, kind of embarrassing. One shouldn't need to be a programmer, or even particularly a geek, to contribute a documentation fix. You'll note I say fix, not patch, because I don't feel that the ability to generate a patch is a particularly important one in a documentation expert. The ability to *write* is, and if we scare off a writer with a poorly-written page, then we've done us and them disservice.

Anyways, enough philosophy. Here's what I'm planning to do in the near future.

The "whodunnit" portion of http://httpd.apache.org/docs-project/ doesn't need to be half of the front page. Unless someone strenuously objects, I'd like to move that to a /docs-project/contributors.html page, and, if possible, look in SVN to make it actually reflect reality a little better.

The top section of the page (the bit with the "Documentation Project" header) is largely filler text. It's nice, but it doesn't really contribute much. The "How to get involved" section is the one that matters. http://people.apache.org/~humbedooh/contribute.html does a better job of saying it, and that's a good starting point. But I'd really like to emphasize in some friendly way that if folks want to fix something, it's adequate to send us email, or put a fixed copy of the HTML somewhere, or send us a letter, or ... you know, generally get that fix to us in any way that they can. The community context comes from the way we welcome that contribution. If the welcome is "no, we need a valid patch in valid XML against the latest HEAD revision", then they'll never stick around long enough to find out what the community context is.

Anyways, that's my soap box. Less talking, more doing. Shosholoza, as they say.

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


nd at perlig

May 3, 2012, 6:54 AM

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

On Thursday 03 May 2012 15:38:32 Rich Bowen wrote:
> On May 3, 2012, at 3:20 AM, André Malo wrote:
> > Yes. Answering those questions above would be a big help. Beside the
> > technical answers we should also point the people to the mailing list to
> > ask their questions.
> > However, I'm also inclined to say, that if we're not able to use our own
> > self-documentation properly, we're doing something very wrong. And it's
> > not very much. Just a few pages. No offense to anyone, but I'm pretty
> > frustrated by the "I would contribute, but I don't bother to get some
> > community context" attitude floating around.
>
> Oh, I don't know about that. I think that we should indeed lower the bar to
> contributing to the docs. I don't think it should be a requirement to learn
> about XML, XSLT, SVN, or Ant in order to say "wouldn't that sentence flow
> better if you said ..." Besides which, the "community context" should be
> one of welcoming, not one of "go read the documentation for our
> documentation before you can tell us we misspelled peony."

Maybe we have a misunderstanding here. That's what I said. It's all not
necessary to know. But nobody bothers to find out. I don't see anybody
asking!
And if I explain these things, nobody cares apparently. From my POV, it seems
to be the same. Whatever we provide, there's always someone who doesn't like
it.

nd

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


i.galic at brainsware

May 3, 2012, 8:52 AM

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

----- Original Message -----
> On Thursday 03 May 2012 15:38:32 Rich Bowen wrote:
> > On May 3, 2012, at 3:20 AM, André Malo wrote:
> > > Yes. Answering those questions above would be a big help. Beside
> > > the
> > > technical answers we should also point the people to the mailing
> > > list to
> > > ask their questions.
> > > However, I'm also inclined to say, that if we're not able to use
> > > our own
> > > self-documentation properly, we're doing something very wrong.
> > > And it's
> > > not very much. Just a few pages. No offense to anyone, but I'm
> > > pretty
> > > frustrated by the "I would contribute, but I don't bother to get
> > > some
> > > community context" attitude floating around.
> >
> > Oh, I don't know about that. I think that we should indeed lower
> > the bar to
> > contributing to the docs. I don't think it should be a requirement
> > to learn
> > about XML, XSLT, SVN, or Ant in order to say "wouldn't that
> > sentence flow
> > better if you said ..." Besides which, the "community context"
> > should be
> > one of welcoming, not one of "go read the documentation for our
> > documentation before you can tell us we misspelled peony."
>
> Maybe we have a misunderstanding here. That's what I said. It's all
> not
> necessary to know. But nobody bothers to find out. I don't see
> anybody
> asking!
> And if I explain these things, nobody cares apparently. From my POV,
> it seems
> to be the same. Whatever we provide, there's always someone who
> doesn't like
> it.

The main reason why nobody is asking is because it's quite an
embarrassing thing to do.

> nd

i

--
Igor Galić

Tel: +43 (0) 664 886 22 883
Mail: i.galic [at] brainsware
URL: http://brainsware.org/
GPG: 6880 4155 74BD FD7C B515 2EA5 4B1D 9E08 A097 C9AE


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


rbowen at rcbowen

May 3, 2012, 2:07 PM

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

Ok, thanks to Tony for hand-holding me a little more through an explanation of how this would work in practice.

I feel that I was responding with inadequate understanding.

So, I'm now firmly +1 on moving the docs to the Apache CMS. There are still parts of the process that are somewhat unclear to me, but we can work that out as we go along, I think.

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


mads at toftum

May 3, 2012, 2:26 PM

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

On Thu, May 03, 2012 at 05:07:12PM -0400, Rich Bowen wrote:
> Ok, thanks to Tony for hand-holding me a little more through an explanation of how this would work in practice.
>
> I feel that I was responding with inadequate understanding.
>
> So, I'm now firmly +1 on moving the docs to the Apache CMS. There are still parts of the process that are somewhat unclear to me, but we can work that out as we go along, I think.
>
I'll stick with my firmly -1 for the time being.
Let's get the website into the CMS first, then we can start considering
whether that new workflow is workable.
Let's not forget that you're in the middle of several other disruptive
projects too - php docs style comments and the carnival colors.
I think the comments will likely be a spam magnet, but casual
contributions would be well covered by that. Making them 0 effort to
submit.
The CMS is a complex beast (yeah, I do know something about it) and
we're currently doing a lot with our docs that do not map well into the
CMS. I can fully understand why Joe wants to expand the capabilities of
the CMS, but it's going to be a major effort both on the infra side and
on our (looking in the general direction of nd) side to make the docs
fit. All for a minimal gain. Once you've looked at the file format a
couple of times, the current files are pretty darn easy to edit and any
clicking around in the cms will take just as long or longer. Given that
you're already planning to solve 0-effort contributions, I don't see the
gain in changing the toolset. We'd still have a committer requirement
for using the CMS, so it's not opening up for wider contributions
anyway.

vh

Mads Toftum
--
http://soulfood.dk

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


pctony at apache

May 3, 2012, 3:06 PM

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

Mads Toftum wrote on Thu, May 03, 2012 at 11:26:41PM +0200:
> On Thu, May 03, 2012 at 05:07:12PM -0400, Rich Bowen wrote:
> > Ok, thanks to Tony for hand-holding me a little more through an explanation of how this would work in practice.
> >
> > I feel that I was responding with inadequate understanding.
> >
> > So, I'm now firmly +1 on moving the docs to the Apache CMS. There are still parts of the process that are somewhat unclear to me, but we can work that out as we go along, I think.
> >
> I'll stick with my firmly -1 for the time being.
> Let's get the website into the CMS first, then we can start considering
> whether that new workflow is workable.
> Let's not forget that you're in the middle of several other disruptive
> projects too - php docs style comments and the carnival colors.
> I think the comments will likely be a spam magnet, but casual
> contributions would be well covered by that. Making them 0 effort to
> submit.
> The CMS is a complex beast (yeah, I do know something about it)

It does not have to be Mads. In its simple form it is a WYSIWYG editor, and review page before publishing. Actually, committers can still commit via svn, as they do now.

> and
> we're currently doing a lot with our docs that do not map well into the
> CMS. I can fully understand why Joe wants to expand the capabilities of
> the CMS,

To be clear this is not a capabilities expansion it is a get another site using the CMS, so they can see how simple it is. If any docs committer is also an ASF member they can edit the main www.a.o site, and then publish it. It actually takes away all the pain of fart arsing about with anakia, ant and all that nonsense. Why not let the CMS do the heavy lifting when it comes to running the build tasks? It could conceivably still create a docs tarball that the RM could grab to be bundled into the release tarball.

> but it's going to be a major effort both on the infra side and
> on our (looking in the general direction of nd) side to make the docs
> fit. All for a minimal gain. Once you've looked at the file format a
> couple of times, the current files are pretty darn easy to edit and any
> clicking around in the cms will take just as long or longer.

Have you used the CMS yet? Aside from the first time you use it, and it sets up your WC of the site in question is smooth, simple and by far a much lower barrier for casual commits.

> Given that
> you're already planning to solve 0-effort contributions, I don't see the
> gain in changing the toolset. We'd still have a committer requirement
> for using the CMS, so it's not opening up for wider contributions
> anyway.

That isn't the aim, AFAICT.

>
> vh
>
> Mads Toftum
> --
> http://soulfood.dk
>
> ---------------------------------------------------------------------
> 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)


joe_schaefer at yahoo

May 4, 2012, 10:54 AM

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

>________________________________
> From: Tony Stevenson <pctony [at] apache>
>To: docs [at] httpd
>Sent: Thursday, May 3, 2012 6:06 PM
>Subject: Re: Proposal to move docs to Apache CMS
>
>Mads Toftum wrote on Thu, May 03, 2012 at 11:26:41PM +0200:
>> On Thu, May 03, 2012 at 05:07:12PM -0400, Rich Bowen wrote:
>> > Ok, thanks to Tony for hand-holding me a little more through\
>> > an explanation of how this would work in practice.
>> >
>> > I feel that I was responding with inadequate understanding.
>> >
>> > So, I'm now firmly +1 on moving the docs to the Apache CMS. There
>> > are still parts of the process that are somewhat unclear to me, but
>> > we can work that out as we go along, I think.
>> >
>> I'll stick with my firmly -1 for the time being.
>> Let's get the website into the CMS first, then we can start considering
>> whether that new workflow is workable.
>> Let's not forget that you're in the middle of several other disruptive
>> projects too - php docs style comments and the carnival colors.
>> I think the comments will likely be a spam magnet, but casual
>> contributions would be well covered by that. Making them 0 effort to
>> submit.
>> The CMS is a complex beast (yeah, I do know something about it)
>
>It does not have to be Mads. In its simple form it is a WYSIWYG editor,
>and review page before publishing.  Actually, committers can still commit
>via svn, as they do now. 


Right, well, the thing is without Andre's support this won't ever fly
as *someone* needs to know enough about the current build system to get
it to work with the CMS.  Basically Andre, the CMS is just CI with a simple

web interface.  In a nutshell, you just need to make the changes I outlined
earlier to get the docs builds to work with the CI scripts in place.

I will need to add support in the CMS for the redirection code to work
with the existing docs trees on the live site, but that's just a few lines
of perl.


The advantage of the web interface as there are no additional prereqs-
anyone (even a non-committer) can use the CMS and edit xml source files
using a syntax-highlighted editor in their browser.  Non-committers
are expected to use the CMS webgui to mail their changes as diffs to
the docs list- regular committers can just commit their changes which

will generate a build.  If the build succeeds buildbot will commit
the results back to the staging tree and make them available on the
staging site.  Upon review of the staging site, any httpd committer
can publish them to the live site using either a perl script or thru
the cms itself.

Using the CMS should be a win-win situation: you only sacrifice whatever
advantages there are of having the build artifacts alongside the sources,
but you get a standard system for building all changes and checking those
back into a separate repo.  Casual editors of the docs do not need to read
ANY documentation on how the build system works or even know where the sources
live in svn- they just use the web interface and let the CMS's systems
worry about all that stuff.  People building for non-CMS targets can continue
to do so, be it to generate CHM docs or for bundling into a release (assuming
they don't want to directly use what's already available on the live site).

HTH.

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


rbowen at rcbowen

May 4, 2012, 11:50 AM

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

On May 4, 2012, at 1:54 PM, Joe Schaefer wrote:

> The advantage of the web interface as there are no additional prereqs-
> anyone (even a non-committer) can use the CMS and edit xml source files
> using a syntax-highlighted editor in their browser. Non-committers
> are expected to use the CMS webgui to mail their changes as diffs to
> the docs list


That's awesome.

I was under the impression that this feature didn't exist yet. This lowers the bar on contributions a long, long way.

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


joe_schaefer at yahoo

May 4, 2012, 12:04 PM

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

It'll be interesting to see how codemirror2 handles
the custom character entities in the httpd docs, but assuming
it doesn't choke there's probably an option to validate
the XML before allowing it to be submitted to the server.

I doubt that's currently turned on, but if the code
does the right thing I might be convinced to enable it.





>________________________________
> From: Rich Bowen <rbowen [at] rcbowen>
>To: docs [at] httpd; Joe Schaefer <joe_schaefer [at] yahoo>
>Sent: Friday, May 4, 2012 2:50 PM
>Subject: Re: Proposal to move docs to Apache CMS
>
>
>
>
>On May 4, 2012, at 1:54 PM, Joe Schaefer wrote:
>
>The advantage of the web interface as there are no additional prereqs-
>>anyone (even a non-committer) can use the CMS and edit xml source files
>>using a syntax-highlighted editor in their browser.  Non-committers
>>are expected to use the CMS webgui to mail their changes as diffs to
>>the docs list
>
>
>That's awesome.
>
>
>I was under the impression that this feature didn't exist yet. This lowers the bar on contributions a long, long way.
>
>
>--
>Rich Bowen
>rbowen [at] rcbowen :: @rbowen
>rbowen [at] apache
>
>
>
>
>
>
>
>
>


i.galic at brainsware

May 4, 2012, 12:18 PM

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

----- Original Message -----
>
>
> It'll be interesting to see how codemirror2 handles
> the custom character entities in the httpd docs, but assuming
> it doesn't choke there's probably an option to validate
> the XML before allowing it to be submitted to the server.
>
> I doubt that's currently turned on, but if the code
> does the right thing I might be convinced to enable it.
>
>
>
>
>
>
>
>
>
>
> From: Rich Bowen <rbowen [at] rcbowen>
> To: docs [at] httpd; Joe Schaefer <joe_schaefer [at] yahoo>
> Sent: Friday, May 4, 2012 2:50 PM
> Subject: Re: Proposal to move docs to Apache CMS
>
>
>
>
>
>
> On May 4, 2012, at 1:54 PM, Joe Schaefer wrote:
>
>
> The advantage of the web interface as there are no additional
> prereqs-
> anyone (even a non-committer) can use the CMS and edit xml source
> files
> using a syntax-highlighted editor in their browser. Non-committers
> are expected to use the CMS webgui to mail their changes as diffs to
> the docs list
>
>
> That's awesome.
>
>
> I was under the impression that this feature didn't exist yet. This
> lowers the bar on contributions a long, long way.


I believe what Rich was talking about is that last time we checked,
the CMS' Web UI needed a valid apache committer login:

https://cms.apache.org/


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


So long,

i

--
Igor Galić

Tel: +43 (0) 664 886 22 883
Mail: i.galic [at] brainsware
URL: http://brainsware.org/
GPG: 6880 4155 74BD FD7C B515 2EA5 4B1D 9E08 A097 C9AE


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


rbowen at rcbowen

May 4, 2012, 12:19 PM

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

On May 4, 2012, at 3:04 PM, Joe Schaefer wrote:

> It'll be interesting to see how codemirror2 handles
> the custom character entities in the httpd docs, but assuming
> it doesn't choke there's probably an option to validate
> the XML before allowing it to be submitted to the server.
> I doubt that's currently turned on, but if the code
> does the right thing I might be convinced to enable it.


Our build script does validation as part of the build process, too.

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


joe_schaefer at yahoo

May 4, 2012, 12:21 PM

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

The "anonymous" passwordless account has been
available for at least 6 months now and is documented
in all the expected places.




>________________________________
> From: Igor Galić <i.galic [at] brainsware>
>To: docs [at] httpd; Joe Schaefer <joe_schaefer [at] yahoo>
>Sent: Friday, May 4, 2012 3:18 PM
>Subject: Re: Proposal to move docs to Apache CMS
>
>
>
>----- Original Message -----
>>
>>
>> It'll be interesting to see how codemirror2 handles
>> the custom character entities in the httpd docs, but assuming
>> it doesn't choke there's probably an option to validate
>> the XML before allowing it to be submitted to the server.
>>
>> I doubt that's currently turned on, but if the code
>> does the right thing I might be convinced to enable it.
>>
>>
>>
>>
>>
>>
>>
>>
>>
>>
>> From: Rich Bowen <rbowen [at] rcbowen>
>> To: docs [at] httpd; Joe Schaefer <joe_schaefer [at] yahoo>
>> Sent: Friday, May 4, 2012 2:50 PM
>> Subject: Re: Proposal to move docs to Apache CMS
>>
>>
>>
>>
>>
>>
>> On May 4, 2012, at 1:54 PM, Joe Schaefer wrote:
>>
>>
>> The advantage of the web interface as there are no additional
>> prereqs-
>> anyone (even a non-committer) can use the CMS and edit xml source
>> files
>> using a syntax-highlighted editor in their browser. Non-committers
>> are expected to use the CMS webgui to mail their changes as diffs to
>> the docs list
>>
>>
>> That's awesome.
>>
>>
>> I was under the impression that this feature didn't exist yet. This
>> lowers the bar on contributions a long, long way.
>
>
>I believe what Rich was talking about is that last time we checked,
>the CMS' Web UI needed a valid apache committer login:
>
>  https://cms.apache.org/
>
>
>> --
>> Rich Bowen
>> rbowen [at] rcbowen :: @rbowen
>> rbowen [at] apache
>>
>
>
>So long,
>
>i
>
>--
>Igor Galić
>
>Tel: +43 (0) 664 886 22 883
>Mail: i.galic [at] brainsware
>URL: http://brainsware.org/
>GPG: 6880 4155 74BD FD7C B515  2EA5 4B1D 9E08 A097 C9AE
>
>
>---------------------------------------------------------------------
>To unsubscribe, e-mail: docs-unsubscribe [at] httpd
>For additional commands, e-mail: docs-help [at] httpd
>
>
>
>


joe_schaefer at yahoo

May 4, 2012, 12:22 PM

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

IME it's a bit of a challenge to get CMS users
to pay attention to the build output, even tho
we provide links to the build in question, so
if we can validate on form submission it will
work out a bit better.




>________________________________
> From: Rich Bowen <rbowen [at] rcbowen>
>To: docs [at] httpd; Joe Schaefer <joe_schaefer [at] yahoo>
>Sent: Friday, May 4, 2012 3:19 PM
>Subject: Re: Proposal to move docs to Apache CMS
>
>
>
>
>On May 4, 2012, at 3:04 PM, Joe Schaefer wrote:
>
>It'll be interesting to see how codemirror2 handles
>>the custom character entities in the httpd docs, but assuming
>>it doesn't choke there's probably an option to validate
>>the XML before allowing it to be submitted to the server.
>>
>>I doubt that's currently turned on, but if the code
>>does the right thing I might be convinced to enable it.
>
>
>Our build script does validation as part of the build process, too.
>
>--
>Rich Bowen
>rbowen [at] rcbowen :: @rbowen
>rbowen [at] apache
>
>
>
>
>
>
>
>
>

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.