You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs@httpd.apache.org by Igor Galić <i....@brainsware.org> on 2012/04/20 14:49:46 UTC
Syntax Highlighting
Hey folks,
for all those who haven't seen them yet, Daniel has started
working on developer documentation:
http://httpd.apache.org/docs/trunk/developer/modguide.html
this also contains syntax highlighting.
I'm a sucker for syntax highlighting, mostly because I couldn't
survive without.
If you've looked at the source code however...
https://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/manual/developer/modguide.xml
you'll notice that the current solution is sub-optimal.
There are a lot of syntax-highlighters. enscript being the
first to come to my mind.
Does someone who know our docs-build system well enough
to modify it so to automagickally highlight <example>
sections? If not, maybe we could organize a session (on
IRC) to do some reverse-engineering.
In any case, we should document the process or the outcome,
so those coming after us won't be put before the exact same
problems.
So long,
i
--
Igor Galić
Tel: +43 (0) 664 886 22 883
Mail: i.galic@brainsware.org
URL: http://brainsware.org/
GPG: 6880 4155 74BD FD7C B515 2EA5 4B1D 9E08 A097 C9AE
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Proposal to move docs to Apache CMS
Posted by André Malo <nd...@perlig.de>.
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@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Proposal to move docs to Apache CMS
Posted by Joe Schaefer <jo...@yahoo.com>.
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....@brainsware.org>
>To: docs@httpd.apache.org; Joe Schaefer <jo...@yahoo.com>
>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 <rb...@rcbowen.com>
>> To: docs@httpd.apache.org; Joe Schaefer <jo...@yahoo.com>
>> 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@rcbowen.com :: @rbowen
>> rbowen@apache.org
>>
>
>
>So long,
>
>i
>
>--
>Igor Galić
>
>Tel: +43 (0) 664 886 22 883
>Mail: i.galic@brainsware.org
>URL: http://brainsware.org/
>GPG: 6880 4155 74BD FD7C B515 2EA5 4B1D 9E08 A097 C9AE
>
>
>---------------------------------------------------------------------
>To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
>For additional commands, e-mail: docs-help@httpd.apache.org
>
>
>
>
Re: Doing the main site first (was Re: Proposal to move docs to Apache CMS)
Posted by Joe Schaefer <jo...@yahoo.com>.
>________________________________
> From: Daniel Gruno <ru...@cord.dk>
>To: docs@httpd.apache.org
>Sent: Sunday, May 6, 2012 8:53 AM
>Subject: Re: Doing the main site first (was Re: Proposal to move docs to Apache CMS)
>
>On 05-05-2012 17:02, Joe Schaefer wrote:
>> Speaking with Daniel on IRC this morning convinced
>> me that pushing for docs CMS adoption at this point
>> remains a hard sell. We both agreed that migrating
>> the main site first to the CMS would be better for all
>> concerned, so let's go that route for now and come back
>> to docs once everyone has had a chance to play with
>> the CMS on a production site that they actually care about.
>>
>> Since the site is a standard Anakia thingy, we have
>> migration tools that will convert the xml to markdown,
>> and I talked Daniel into coming up with a simple django
>> template for the site. That means we can use the CMS's
>> standard perl build stuff instead of the largeish collection
>> of java utils that generate the html- its a whole lot
>> simpler and faster in practice once the docs have been
>> migrated.
>>
>> We can leave any .html and .txt documents as-is, they
>> won't be changed by the build. Another thing I'd like
>> to see us do is move the download.cgi script out of the
>> doctree and into a separate cgi-bin/ dir, just so we can
>> actually practice what we preach ;-). The CMS fully
>> supports that.
>>
>> Anyhow if we can find consensus on this plan we can take
>> this back to dev@ and look for general approval.
>>
>> Thoughts?
>>
>
>+1 to that, obviously, since I'm working on a template already. It's
>located at http://httpd.humbedooh.com/cms/trunk/ by the way, in case
>anyone wants to snoop. And if you do, you'll see that it's quite simple
>to migrate, as all we need to do is convert our existing pages into
>markdown via the anakia2markdown script (
>https://svn.apache.org/repos/infra/websites/cms/conversion-utilities/anakia2markdown.xslt
>) and add them to the content directory, and the CMS will take care of
>building and what not. A little grunt work is expected, in order to make
>the pages conform completely, but as we have so few pages on our main
>site, it's really of no concern.
>
>I would, of course, suggest we first set up some form of testing area,
>so we can try wrapping our heads around it and get it working before we
>migrate completely :)
Now that everything's in svn I've gone ahead and activated the CMS for
httpd (sans production). The staging site is available at
http://httpd.staging.apache.org/
Once we're satisfied that everything's ready to go live, we'll vote ;-).
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Doing the main site first (was Re: Proposal to move docs to Apache
CMS)
Posted by Daniel Gruno <ru...@cord.dk>.
On 05-05-2012 17:02, Joe Schaefer wrote:
> Speaking with Daniel on IRC this morning convinced
> me that pushing for docs CMS adoption at this point
> remains a hard sell. We both agreed that migrating
> the main site first to the CMS would be better for all
> concerned, so let's go that route for now and come back
> to docs once everyone has had a chance to play with
> the CMS on a production site that they actually care about.
>
> Since the site is a standard Anakia thingy, we have
> migration tools that will convert the xml to markdown,
> and I talked Daniel into coming up with a simple django
> template for the site. That means we can use the CMS's
> standard perl build stuff instead of the largeish collection
> of java utils that generate the html- its a whole lot
> simpler and faster in practice once the docs have been
> migrated.
>
> We can leave any .html and .txt documents as-is, they
> won't be changed by the build. Another thing I'd like
> to see us do is move the download.cgi script out of the
> doctree and into a separate cgi-bin/ dir, just so we can
> actually practice what we preach ;-). The CMS fully
> supports that.
>
> Anyhow if we can find consensus on this plan we can take
> this back to dev@ and look for general approval.
>
> Thoughts?
>
+1 to that, obviously, since I'm working on a template already. It's
located at http://httpd.humbedooh.com/cms/trunk/ by the way, in case
anyone wants to snoop. And if you do, you'll see that it's quite simple
to migrate, as all we need to do is convert our existing pages into
markdown via the anakia2markdown script (
https://svn.apache.org/repos/infra/websites/cms/conversion-utilities/anakia2markdown.xslt
) and add them to the content directory, and the CMS will take care of
building and what not. A little grunt work is expected, in order to make
the pages conform completely, but as we have so few pages on our main
site, it's really of no concern.
I would, of course, suggest we first set up some form of testing area,
so we can try wrapping our heads around it and get it working before we
migrate completely :)
With regards,
Daniel.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Doing the main site first (was Re: Proposal to move docs to Apache CMS)
Posted by Rich Bowen <rb...@rcbowen.com>.
On May 5, 2012, at 11:02 AM, Joe Schaefer wrote:
> Speaking with Daniel on IRC this morning convinced
> me that pushing for docs CMS adoption at this point
> remains a hard sell. We both agreed that migrating
> the main site first to the CMS would be better for all
> concerned, so let's go that route for now and come back
> to docs once everyone has had a chance to play with
> the CMS on a production site that they actually care about.
>
> Since the site is a standard Anakia thingy, we have
> migration tools that will convert the xml to markdown,
> and I talked Daniel into coming up with a simple django
> template for the site. That means we can use the CMS's
> standard perl build stuff instead of the largeish collection
> of java utils that generate the html- its a whole lot
> simpler and faster in practice once the docs have been
> migrated.
>
> We can leave any .html and .txt documents as-is, they
> won't be changed by the build. Another thing I'd like
> to see us do is move the download.cgi script out of the
> doctree and into a separate cgi-bin/ dir, just so we can
> actually practice what we preach ;-). The CMS fully
> supports that.
>
> Anyhow if we can find consensus on this plan we can take
> this back to dev@ and look for general approval.
Yes, this is the right way to go as a first step. +1
--
Rich Bowen
rbowen@rcbowen.com :: @rbowen
rbowen@apache.org
Doing the main site first (was Re: Proposal to move docs to Apache CMS)
Posted by Joe Schaefer <jo...@yahoo.com>.
Speaking with Daniel on IRC this morning convinced
me that pushing for docs CMS adoption at this point
remains a hard sell. We both agreed that migrating
the main site first to the CMS would be better for all
concerned, so let's go that route for now and come back
to docs once everyone has had a chance to play with
the CMS on a production site that they actually care about.
Since the site is a standard Anakia thingy, we have
migration tools that will convert the xml to markdown,
and I talked Daniel into coming up with a simple django
template for the site. That means we can use the CMS's
standard perl build stuff instead of the largeish collection
of java utils that generate the html- its a whole lot
simpler and faster in practice once the docs have been
migrated.
We can leave any .html and .txt documents as-is, they
won't be changed by the build. Another thing I'd like
to see us do is move the download.cgi script out of the
doctree and into a separate cgi-bin/ dir, just so we can
actually practice what we preach ;-). The CMS fully
supports that.
Anyhow if we can find consensus on this plan we can take
this back to dev@ and look for general approval.
Thoughts?
>________________________________
> From: Joe Schaefer <jo...@yahoo.com>
>To: "docs@httpd.apache.org" <do...@httpd.apache.org>
>Sent: Friday, May 4, 2012 3:22 PM
>Subject: Re: Proposal to move docs to Apache CMS
>
>
>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 <rb...@rcbowen.com>
>>To: docs@httpd.apache.org; Joe Schaefer <jo...@yahoo.com>
>>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@rcbowen.com :: @rbowen
>>rbowen@apache.org
>>
>>
>>
>>
>>
>>
>>
>>
>>
>
>
Re: Proposal to move docs to Apache CMS
Posted by Joe Schaefer <jo...@yahoo.com>.
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 <rb...@rcbowen.com>
>To: docs@httpd.apache.org; Joe Schaefer <jo...@yahoo.com>
>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@rcbowen.com :: @rbowen
>rbowen@apache.org
>
>
>
>
>
>
>
>
>
Re: Proposal to move docs to Apache CMS
Posted by Rich Bowen <rb...@rcbowen.com>.
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@rcbowen.com :: @rbowen
rbowen@apache.org
Re: Proposal to move docs to Apache CMS
Posted by Igor Galić <i....@brainsware.org>.
----- 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 <rb...@rcbowen.com>
> To: docs@httpd.apache.org; Joe Schaefer <jo...@yahoo.com>
> 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@rcbowen.com :: @rbowen
> rbowen@apache.org
>
So long,
i
--
Igor Galić
Tel: +43 (0) 664 886 22 883
Mail: i.galic@brainsware.org
URL: http://brainsware.org/
GPG: 6880 4155 74BD FD7C B515 2EA5 4B1D 9E08 A097 C9AE
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Proposal to move docs to Apache CMS
Posted by Joe Schaefer <jo...@yahoo.com>.
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 <rb...@rcbowen.com>
>To: docs@httpd.apache.org; Joe Schaefer <jo...@yahoo.com>
>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@rcbowen.com :: @rbowen
>rbowen@apache.org
>
>
>
>
>
>
>
>
>
Re: Proposal to move docs to Apache CMS
Posted by Rich Bowen <rb...@rcbowen.com>.
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@rcbowen.com :: @rbowen
rbowen@apache.org
Re: Proposal to move docs to Apache CMS
Posted by Joe Schaefer <jo...@yahoo.com>.
>________________________________
> From: Tony Stevenson <pc...@apache.org>
>To: docs@httpd.apache.org
>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@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Proposal to move docs to Apache CMS
Posted by Tony Stevenson <pc...@apache.org>.
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@httpd.apache.org
> For additional commands, e-mail: docs-help@httpd.apache.org
>
--
Cheers,
Tony
---------------------------------------
Tony Stevenson
tony@pc-tony.com // pctony@apache.org
tony@caret.cam.ac.uk
http://blog.pc-tony.com
GPG - 1024D/51047D66
--------------------------------------"
Re: Proposal to move docs to Apache CMS
Posted by Mads Toftum <ma...@toftum.dk>.
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@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Proposal to move docs to Apache CMS
Posted by Rich Bowen <rb...@rcbowen.com>.
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@rcbowen.com :: @rbowen
rbowen@apache.org
Re: Proposal to move docs to Apache CMS
Posted by Igor Galić <i....@brainsware.org>.
----- 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@brainsware.org
URL: http://brainsware.org/
GPG: 6880 4155 74BD FD7C B515 2EA5 4B1D 9E08 A097 C9AE
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Proposal to move docs to Apache CMS
Posted by André Malo <nd...@perlig.de>.
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@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Proposal to move docs to Apache CMS
Posted by Rich Bowen <rb...@rcbowen.com>.
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@rcbowen.com :: @rbowen
rbowen@apache.org
Re: Proposal to move docs to Apache CMS
Posted by Daniel Gruno <ru...@cord.dk>.
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@h.a.o 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@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Proposal to move docs to Apache CMS
Posted by André Malo <nd...@perlig.de>.
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@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Syntax Highlighting, part 2
Posted by Daniel Ruggeri <DR...@primary.net>.
On 5/2/2012 8:14 AM, Rich Bowen wrote:
> +1. I'd like to see the highlighting changes ported over to the 2.4
> docs. I don't see any value in having them in the 2.2 docs.
>
Another +1 from me. It looks great.
>
> Yes, I expect that the styles can be further tweaked, but I like
> what's there currently. Subtle enough that it's not a circus
> billboard, but vivid enough that you can tell what's going on.
Well stated.
--
Daniel Ruggeri
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Syntax Highlighting, part 2
Posted by Rich Bowen <rb...@rcbowen.com>.
On May 1, 2012, at 12:20 PM, Daniel Gruno wrote:
> Hello docs@,
>
> I have read the responses from people on both the mailing list, off it,
> and via other channels, as well as made a small non-scientific survey
> among the users@ people that showed a big approval (93%) of adding
> highlighting to the documentation, and it makes me quite happy that
> people are enthusiastic about this project and the proposed changes.
>
> I would therefor like to propose, that we apply these changes to the 2.4
> branch as well, so the community can benefit from this highlighting when
> visiting /current/. It is my belief that it would ease the process of
> reading example configurations and source code, enabling users to
> quickly get the information they need, without having to "mentally
> highlight" it themselves.
>
> As we have a certain saying about our mailing lists, I would ask that
> people that are both for and against this speak up on this list, so we
> can see if there is a general consensus for backporting these changes.
>
+1. I'd like to see the highlighting changes ported over to the 2.4 docs. I don't see any value in having them in the 2.2 docs.
Over the coming months as trunk doc changes are copied over to 2.4, highlighting will begin to appear here and there. Only by doing the whole enchilada can we have any kind of consistency across the documentation.
Yes, I expect that the styles can be further tweaked, but I like what's there currently. Subtle enough that it's not a circus billboard, but vivid enough that you can tell what's going on.
--
Rich Bowen
rbowen@rcbowen.com :: @rbowen
rbowen@apache.org
Re: Syntax Highlighting, part 2
Posted by Igor Galić <i....@brainsware.org>.
----- Original Message -----
> On 03-05-2012 15:49, Lucien Gentis wrote:
> >>
> > Just a question : is there a way to automate the update process of
> > add/replace <highlight> tags in xml files ?
> > (something like replacing all <example> tags by <highlight> tags)
> > But all <example> tags are not replaced, when there's a title,
> > <highlight> tag is added . . .
> >
> > I'm just beginning updating trunk branch, and I don't know when
> > I'll be
> > finished !
> >
> > So, if we must make again the same work for 2.4 branch, I don't
> > know if
> > I'll reach the end during my current life.
> >
> > Lucien
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
> > For additional commands, e-mail: docs-help@httpd.apache.org
> >
>
> Oh, it was a pain in the bee-hind for me to transform all the docs as
> well ;) I found that I could automate a lot of it using multi-line
> regexp edits with UltraEdit, but in the end, most of it is just plain
> old grunt work, especially because people tend to put silly titles in
> the examples, "Example" being the dominant title of examples...d'uh.
>
> As for the 2.4 branch, I suspect we'll be directly backporting most
> of
> the stuff we have in trunk right now, since most of what we have in
> trunk is what we should have in 2.4 by now. So I wouldn't be too
> worried
> about how much work porting it to 2.4 will be.
I've attempted to backport a couple of the newly highlighted
French/Korean/Japanese/German docs myself, but I just couldn't
keep up with Daniel. He's got too damn much time on his hands :P
> With regards,
> Daniel.
i
--
Igor Galić
Tel: +43 (0) 664 886 22 883
Mail: i.galic@brainsware.org
URL: http://brainsware.org/
GPG: 6880 4155 74BD FD7C B515 2EA5 4B1D 9E08 A097 C9AE
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Syntax Highlighting, part 2
Posted by Daniel Gruno <ru...@cord.dk>.
On 03-05-2012 15:49, Lucien Gentis wrote:
>>
> Just a question : is there a way to automate the update process of
> add/replace <highlight> tags in xml files ?
> (something like replacing all <example> tags by <highlight> tags)
> But all <example> tags are not replaced, when there's a title,
> <highlight> tag is added . . .
>
> I'm just beginning updating trunk branch, and I don't know when I'll be
> finished !
>
> So, if we must make again the same work for 2.4 branch, I don't know if
> I'll reach the end during my current life.
>
> Lucien
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
> For additional commands, e-mail: docs-help@httpd.apache.org
>
Oh, it was a pain in the bee-hind for me to transform all the docs as
well ;) I found that I could automate a lot of it using multi-line
regexp edits with UltraEdit, but in the end, most of it is just plain
old grunt work, especially because people tend to put silly titles in
the examples, "Example" being the dominant title of examples...d'uh.
As for the 2.4 branch, I suspect we'll be directly backporting most of
the stuff we have in trunk right now, since most of what we have in
trunk is what we should have in 2.4 by now. So I wouldn't be too worried
about how much work porting it to 2.4 will be.
With regards,
Daniel.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Syntax Highlighting, part 2
Posted by Lucien Gentis <lu...@medecine.uhp-nancy.fr>.
Le 01/05/12 18:20, Daniel Gruno a écrit :
> Hello docs@,
>
> I have read the responses from people on both the mailing list, off it,
> and via other channels, as well as made a small non-scientific survey
> among the users@ people that showed a big approval (93%) of adding
> highlighting to the documentation, and it makes me quite happy that
> people are enthusiastic about this project and the proposed changes.
>
> I would therefor like to propose, that we apply these changes to the 2.4
> branch as well, so the community can benefit from this highlighting when
> visiting /current/. It is my belief that it would ease the process of
> reading example configurations and source code, enabling users to
> quickly get the information they need, without having to "mentally
> highlight" it themselves.
>
> As we have a certain saying about our mailing lists, I would ask that
> people that are both for and against this speak up on this list, so we
> can see if there is a general consensus for backporting these changes.
>
> Finally, I should remark that things like how it's highlighted and which
> styles are used, can always be changed, so if you have any comments
> about that, please voice those as well :)
>
> With regards,
> Daniel.
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
> For additional commands, e-mail: docs-help@httpd.apache.org
>
Just a question : is there a way to automate the update process of
add/replace <highlight> tags in xml files ?
(something like replacing all <example> tags by <highlight> tags)
But all <example> tags are not replaced, when there's a title,
<highlight> tag is added . . .
I'm just beginning updating trunk branch, and I don't know when I'll be
finished !
So, if we must make again the same work for 2.4 branch, I don't know if
I'll reach the end during my current life.
Lucien
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Syntax Highlighting, part 2
Posted by Daniel Gruno <ru...@cord.dk>.
Hello docs@,
I have read the responses from people on both the mailing list, off it,
and via other channels, as well as made a small non-scientific survey
among the users@ people that showed a big approval (93%) of adding
highlighting to the documentation, and it makes me quite happy that
people are enthusiastic about this project and the proposed changes.
I would therefor like to propose, that we apply these changes to the 2.4
branch as well, so the community can benefit from this highlighting when
visiting /current/. It is my belief that it would ease the process of
reading example configurations and source code, enabling users to
quickly get the information they need, without having to "mentally
highlight" it themselves.
As we have a certain saying about our mailing lists, I would ask that
people that are both for and against this speak up on this list, so we
can see if there is a general consensus for backporting these changes.
Finally, I should remark that things like how it's highlighted and which
styles are used, can always be changed, so if you have any comments
about that, please voice those as well :)
With regards,
Daniel.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Syntax Highlighting
Posted by Daniel Gruno <ru...@cord.dk>.
On 28-04-2012 04:00, Daniel Ruggeri wrote:
> Do you have a few examples of different highlighters for different
> languages?
> http://httpd.apache.org/docs/trunk/mod/mod_proxy.html and
> http://httpd.apache.org/docs/trunk/mod/core.html ... seem to be great
> examples of httpd config highlighting. This. Looks. Awesome.
> FWIW, I noticed a little weirdness on mod_proxy.html#envsettings (where
> "proxy" seems to be highlighted out of context).
>
> http://httpd.apache.org/docs/trunk/mod/mod_asis.html ... is an HTML
> highlighter an option?
>
I'm unsure what you mean by different highlighters. If you mean
different types of software, then no - we kind'a had to stick with one
that was licensed with ASL, and the one we picked felt like the best
choice for an all-round highlighting.
If you merely mean how the existing highlighter works with different
languages, then there's plenty of examples in the docs:
Lua: http://httpd.apache.org/docs/trunk/mod/mod_lua.html
Perl: http://httpd.apache.org/docs/trunk/howto/cgi.html#writing
C: http://httpd.apache.org/docs/trunk/developer/modguide.html#snippets
As I probably mentioned, these different languages can be styled
individually, so if anyone feels strongly about a specific style, we can
accommodate that.
As for HTML highlighting, it is possible by simply changing the
<example> in mod_asis.xml to <highlight language="html">, but I'm having
some difficulty building the file after I do that, so I'll have to link
off-site for an example:
http://www.humbedooh.com/apache/mod_asis.html.en
As for the weirdness, I have ironed that out for the moment by making
the lexer a bit stricter when it comes to section directives, but some
further tweaking is still needed, as the httpd config highlights are,
surprise surprise, not part of the standard highlighting feature, so we
had to build that ourselves. I hope this answers your questions, and if
not, just write back and such :)
With regards,
Daniel.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Proposal to move docs to Apache CMS
Posted by André Malo <nd...@perlig.de>.
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 <ru...@cord.dk>
> > To: docs@httpd.apache.org
> > 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@httpd.apache.org
> For additional commands, e-mail: docs-help@httpd.apache.org
--
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@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Proposal to move docs to Apache CMS
Posted by Rich Bowen <rb...@rcbowen.com>.
> 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.
Re: Proposal to move docs to Apache CMS
Posted by Igor Galić <i....@brainsware.org>.
> 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@brainsware.org
URL: http://brainsware.org/
GPG: 6880 4155 74BD FD7C B515 2EA5 4B1D 9E08 A097 C9AE
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Proposal to move docs to Apache CMS
Posted by André Malo <nd...@perlig.de>.
On Thursday 03 May 2012 02:56:12 Rich Bowen wrote:
> On 2012 5 2 20:49, "Joe Schaefer" <jo...@yahoo.com> 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@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Proposal to move docs to Apache CMS
Posted by Rich Bowen <rb...@rcbowen.com>.
On 2012 5 2 20:49, "Joe Schaefer" <jo...@yahoo.com> 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.
Re: Proposal to move docs to Apache CMS
Posted by Joe Schaefer <jo...@yahoo.com>.
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 <rb...@rcbowen.com>
>To: docs@httpd.apache.org
>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" <ru...@cord.dk> 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.
>
>
>
Re: Proposal to move docs to Apache CMS
Posted by Rich Bowen <rb...@rcbowen.com>.
On 2012 5 2 18:52, "Daniel Gruno" <ru...@cord.dk> 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.
Re: Proposal to move docs to Apache CMS
Posted by Daniel Gruno <ru...@cord.dk>.
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@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Proposal to move docs to Apache CMS
Posted by Daniel Gruno <ru...@cord.dk>.
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@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Proposal to move docs to Apache CMS
Posted by Tony Stevenson <pc...@apache.org>.
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...@perlig.de> 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@pc-tony.com // pctony@apache.org
tony@caret.cam.ac.uk
http://blog.pc-tony.com
GPG - 1024D/51047D66
--------------------------------------"
Re: Proposal to move docs to Apache CMS
Posted by Nóirín Plunkett <no...@apache.org>.
On Wed, May 2, 2012 at 3:07 PM, André Malo <nd...@perlig.de> 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@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Proposal to move docs to Apache CMS
Posted by André Malo <nd...@perlig.de>.
* 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@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Proposal to move docs to Apache CMS
Posted by André Malo <nd...@perlig.de>.
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@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Proposal to move docs to Apache CMS
Posted by Rich Bowen <rb...@rcbowen.com>.
> >
> > 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?
Re: Proposal to move docs to Apache CMS
Posted by Tony Stevenson <pc...@apache.org>.
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...@perlig.de> 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@httpd.apache.org
> For additional commands, e-mail: docs-help@httpd.apache.org
>
--
Cheers,
Tony
---------------------------------------
Tony Stevenson
tony@pc-tony.com // pctony@apache.org
tony@caret.cam.ac.uk
http://blog.pc-tony.com
GPG - 1024D/51047D66
--------------------------------------"
Re: Proposal to move docs to Apache CMS
Posted by Nóirín Plunkett <no...@apache.org>.
On Wed, May 2, 2012 at 2:40 PM, André Malo <nd...@perlig.de> 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@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Proposal to move docs to Apache CMS
Posted by Tony Stevenson <pc...@apache.org>.
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@pc-tony.com // pctony@apache.org
tony@caret.cam.ac.uk
http://blog.pc-tony.com
GPG - 1024D/51047D66
--------------------------------------"
Re: Proposal to move docs to Apache CMS
Posted by Tony Stevenson <pc...@apache.org>.
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@httpd.apache.org
> For additional commands, e-mail: docs-help@httpd.apache.org
>
--
Cheers,
Tony
---------------------------------------
Tony Stevenson
tony@pc-tony.com // pctony@apache.org
tony@caret.cam.ac.uk
http://blog.pc-tony.com
GPG - 1024D/51047D66
--------------------------------------"
Re: Proposal to move docs to Apache CMS
Posted by Daniel Gruno <ru...@cord.dk>.
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@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Proposal to move docs to Apache CMS
Posted by André Malo <nd...@perlig.de>.
* Nóirín Plunkett wrote:
> On Mon, Apr 30, 2012 at 8:36 AM, Daniel Gruno <ru...@cord.dk> 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@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Proposal to move docs to Apache CMS
Posted by André Malo <nd...@perlig.de>.
* 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@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Proposal to move docs to Apache CMS
Posted by Stefan Fritsch <sf...@sfritsch.de>.
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@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Proposal to move docs to Apache CMS
Posted by André Malo <nd...@perlig.de>.
* 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@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Proposal to move docs to Apache CMS
Posted by Rich Bowen <rb...@rcbowen.com>.
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@rcbowen.com :: @rbowen
rbowen@apache.org
Re: Proposal to move docs to Apache CMS
Posted by Rich Bowen <rb...@rcbowen.com>.
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@rcbowen.com :: @rbowen
rbowen@apache.org
Re: Proposal to move docs to Apache CMS
Posted by Nóirín Plunkett <no...@apache.org>.
On Mon, Apr 30, 2012 at 8:36 AM, Daniel Gruno <ru...@cord.dk> 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@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Proposal to move docs to Apache CMS
Posted by Mads Toftum <ma...@toftum.dk>.
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@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Proposal to move docs to Apache CMS
Posted by Joe Schaefer <jo...@yahoo.com>.
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 <jo...@yahoo.com>
> To: "docs@httpd.apache.org" <do...@httpd.apache.org>
> Cc:
> Sent: Monday, April 30, 2012 12:46 PM
> Subject: Re: Proposal to move docs to Apache CMS
>
> ----- Original Message -----
>
>> From: Daniel Gruno <ru...@cord.dk>
>> To: docs@httpd.apache.org
>> 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@httpd.apache.org
> For additional commands, e-mail: docs-help@httpd.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Proposal to move docs to Apache CMS
Posted by Joe Schaefer <jo...@yahoo.com>.
----- Original Message -----
> From: Daniel Gruno <ru...@cord.dk>
> To: docs@httpd.apache.org
> 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@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Proposal to move docs to Apache CMS
Posted by Daniel Gruno <ru...@cord.dk>.
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@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Syntax Highlighting
Posted by Daniel Ruggeri <DR...@primary.net>.
On 4/27/2012 10:28 AM, Daniel Gruno wrote:
> 1) We have added a syntax highlighter in JavaScript, making it possible
> to disable the highlighting by simply disabling JavaScript for
> httpd.a.o. The files added for this are prettify.js, an ASL highlighter
> which has been heavily modified by us to accommodate our needs and
> prettify.css, which takes care of the CSS requirements and allows us to
> style each language (C, Perl, Lua and Apache Config) separately.
Do you have a few examples of different highlighters for different
languages?
http://httpd.apache.org/docs/trunk/mod/mod_proxy.html and
http://httpd.apache.org/docs/trunk/mod/core.html ... seem to be great
examples of httpd config highlighting. This. Looks. Awesome.
FWIW, I noticed a little weirdness on mod_proxy.html#envsettings (where
"proxy" seems to be highlighted out of context).
http://httpd.apache.org/docs/trunk/mod/mod_asis.html ... is an HTML
highlighter an option?
--
Daniel Ruggeri
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Syntax Highlighting
Posted by Daniel Gruno <ru...@cord.dk>.
As some of you may have noticed, there has been quite a lot of traffic
in commits@ these past few days. We have been testing out the new syntax
highlighting feature, and decided to give it an actual go, rolling out
highlighting for the entire trunk. The response has been quite positive,
and we (Rich, Igor, myself and others who have responded on IRC, Twitter
and other non-docs@ sources) are confident that this is a big boost in
user friendliness.
This email is to describe the changes that have been going on:
1) We have added a syntax highlighter in JavaScript, making it possible
to disable the highlighting by simply disabling JavaScript for
httpd.a.o. The files added for this are prettify.js, an ASL highlighter
which has been heavily modified by us to accommodate our needs and
prettify.css, which takes care of the CSS requirements and allows us to
style each language (C, Perl, Lua and Apache Config) separately.
2) A new tag has been added to the XSLT system called <highlight>. To
enable highlighting of a configuration example, all you need to do is
write, for example:
<highlight language="config">
NameVirtualHosts *:80
</highlight>
To make an example with a title, you can nest highlights within
<example> tags like so:
<example>
<title>Title goes here</title>
<highlight language="config">
DocumentRoot "/foo/bar"
</highlight>
</example>
Please note that this translates into a <pre> tag, so it does not nest
within already existing <pre> tags. Also, as this is a <pre> tag, code
should not have leading spaces unless you need to show nesting of code,
as this will not translate pretty (at least not yet). You can review the
XML changes to see exactly what is meant by this.
3) All valid httpd directives are known by this new highlighting system,
which also makes for an easy way to spot mistyped directives in your
examples.
4) To the best of my knowledge, all documents in trunk have been updated
to use the new <highlight> tag instead of the old combinations of
<example>, <pre>, <code> or whichever system was being used on a
specific page. The various <indent> and <br /> tags have similarly been
removed, leaving leaner and easier to edit examples. And should we
decide to revert some or all of the highlighting, we can simply disable
the JavaScript for those portions and everything will look like it did
before.
I hope you will all check out these changes to our documentation, and
give it some time to sink in. I know that these changes may seem like a
big change to some of you, but I assure you that we only have the best
intentions for our users in mind when we do major overhauls like this,
and even though something has been out there for 10 years, it can still
be in need of an update now and then :).
So, check it out, give some feedback and let's see where the wind takes us.
With regards,
Daniel.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Syntax Highlighting
Posted by Rich Bowen <rb...@rcbowen.com>.
On Apr 25, 2012, at 8:50 AM, Mads Toftum wrote:
> there's a very fine line between config
> highlighting and looking like a neon sign.
Yes. This I agree with, and it's why I always cart my .vimrc around with me, because I find many of the default themes to be eye-bleeding-inducing.
Syntax highlighting contributes to understanding, when it's done well, and contributes to overlooking important, but poorly color-coded, parts of the text when it's not done well.
We should tweak the CSS until we arrive at something that is the former - pointing out the different "parts of speech", but not in such a way that it's jarring.
--
Rich Bowen
rbowen@rcbowen.com :: @rbowen
rbowen@apache.org
Re: Syntax Highlighting
Posted by Mads Toftum <ma...@toftum.dk>.
On Wed, Apr 25, 2012 at 10:13:46AM -0000, Igor Gali?? wrote:
>
> We had some discussion on IRC, and Daniel fixed up a test with
> syntax highlighting for Configuration sections. Rich suggested
> we keep it with the bluish grey that we've trained people to
> look for. The outcome is this:
>
> http://www.humbedooh.com/apache/perf-scaling.html.en#Caching%20Content
>
>
Not a fan at all. I'm not too keen on having javascript be part of
rendering the docs and there's a very fine line between config
highlighting and looking like a neon sign. It's not too bad in a larger
section, but I find it less readable on short snippets of only a few
lines. To see what I'm talking about, look at the 3 line snippet at the
end of the section - there I think the color takes up too much
attention.
So my preference would be clearly in favor of only coloring code and if
we must, some of the larger Configuration examples.
vh
Mads Toftum
--
http://soulfood.dk
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Syntax Highlighting
Posted by Daniel Gruno <ru...@cord.dk>.
On 25-04-2012 12:13, Igor Galić wrote:
>
> We had some discussion on IRC, and Daniel fixed up a test with
> syntax highlighting for Configuration sections. Rich suggested
> we keep it with the bluish grey that we've trained people to
> look for. The outcome is this:
>
> http://www.humbedooh.com/apache/perf-scaling.html.en#Caching%20Content
>
> It looks very nice and subtle.
>
> I would like to suggest we apply it to existing configs.
>
> This is also a good chance to revisit our configuration examples
> to follow our own best-practices :)
>
> So long,
>
> i
>
+1 to this!
First off, since this is done via JavaScript, people that do not like it
can simply turn off JS on httpd.a.o and it won't bother them, so that's
a good thing compared to making it permanent inside the html code.
Secondly, it makes (for my part at least) the configurations easier to
read, since we have tweaked the lexer to recognize valid httpd
directives and enclosures. When looking at the example you linked, and
comparing it to the original, there is no doubt in my mind, that -
regardless of what people might think of the colors used - it is far
easier to read the configuration that is styled than the plain text version.
Thirdly, as pointed out by wrowe on IRC, this may also be a good
incentive to write properly formed configuration examples, as the better
they are written, the better they will be styled. As an example, using
quotation marks around a path in a directive will make it stand out as a
string literal, which will both be easier to distinguish as well as a
good practice for especially porting examples to Windows, where there is
often a space or two in the paths, which would require quotations. For
instance, _DocumentRoot "/foo/bar/baz"_ would be preferable to
_DocumentRoot /foo/bar/baz_ as the former can be ported to systems where
the path might be "/some spaces/here and there/apache".
Finally, it means we can get rid of all the <indent> and <br/> code in
our examples, which will make editing (especially C/Lua/Perl source
code) a whole lot easier.
So, to conclude, I'm all for us trying this out.
With regards,
Daniel.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Syntax Highlighting
Posted by Igor Galić <i....@brainsware.org>.
We had some discussion on IRC, and Daniel fixed up a test with
syntax highlighting for Configuration sections. Rich suggested
we keep it with the bluish grey that we've trained people to
look for. The outcome is this:
http://www.humbedooh.com/apache/perf-scaling.html.en#Caching%20Content
It looks very nice and subtle.
I would like to suggest we apply it to existing configs.
This is also a good chance to revisit our configuration examples
to follow our own best-practices :)
So long,
i
----- Original Message -----
> * Daniel Gruno wrote:
>
> > After hearing some concerns expressed over whether we could include
> > a
> > GPL3 licensed script in our documentation, I have looked for
> > alternate
> > solutions, and found a syntax highlighter that it Apache 2.0
> > licensed.
>
> Oh, well.
>
> > This requires a small change to the common.xsl file (revert the
> > previous
> > changed and apply this new patch instead, if you want to try it
> > out),
> > and two additional files, which I have placed in the trunk (a js
> > and a
> > css file).
>
> The patch looks ok, just minor comments from me:
>
> - Please avoid unrelated whitespace changes
>
> + if (prettyPrint) {
>
> this won't work in case of missing external JS. You need to check for
> window.prettyPrint or typeof(prettyPrint)!==undefined.
>
> nd
> --
> 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@httpd.apache.org
> For additional commands, e-mail: docs-help@httpd.apache.org
>
>
--
Igor Galić
Tel: +43 (0) 664 886 22 883
Mail: i.galic@brainsware.org
URL: http://brainsware.org/
GPG: 6880 4155 74BD FD7C B515 2EA5 4B1D 9E08 A097 C9AE
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Syntax Highlighting
Posted by André Malo <nd...@perlig.de>.
* Daniel Gruno wrote:
> After hearing some concerns expressed over whether we could include a
> GPL3 licensed script in our documentation, I have looked for alternate
> solutions, and found a syntax highlighter that it Apache 2.0 licensed.
Oh, well.
> This requires a small change to the common.xsl file (revert the previous
> changed and apply this new patch instead, if you want to try it out),
> and two additional files, which I have placed in the trunk (a js and a
> css file).
The patch looks ok, just minor comments from me:
- Please avoid unrelated whitespace changes
+ if (prettyPrint) {
this won't work in case of missing external JS. You need to check for
window.prettyPrint or typeof(prettyPrint)!==undefined.
nd
--
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@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Syntax Highlighting
Posted by Daniel Gruno <ru...@cord.dk>.
After hearing some concerns expressed over whether we could include a
GPL3 licensed script in our documentation, I have looked for alternate
solutions, and found a syntax highlighter that it Apache 2.0 licensed.
This requires a small change to the common.xsl file (revert the previous
changed and apply this new patch instead, if you want to try it out),
and two additional files, which I have placed in the trunk (a js and a
css file).
An example of a file built with this new highlighter can be seen at
http://www.humbedooh.com/apache/modguide.html.en#snippets
The syntax is still the same, although this new "test subject" is more
agile and can highlight most code without the need for importing
external language definitions;
<highlight language="c">
static void* foo_function(bar, NULL)
{
printf("Hello, world!");
}
</highlight>
With regards,
Daniel.
Re: Syntax Highlighting
Posted by Daniel Gruno <ru...@cord.dk>.
On 24-04-2012 15:30, André Malo wrote:
>> 1) Modify common.dtd to allow classes inside <pre> tags
>> 2) Modify common.xsl to include the style sheet and scripts used for
>> highlighting the source code examples in our documentation.
>>
>> To create syntax highlighted source code examples, the only requirement
>> would be that you use the following syntax:
>>
>> <pre class="sh_c">
>> code_goes_here(foo);
>> </pre>
>
> I'd prefer a different element on xml side. Like <highlight language="perl">
> or <syntax>.
> Otherwise I like the javascript solution.
>
> nd
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
> For additional commands, e-mail: docs-help@httpd.apache.org
>
The idea of a separate <highlight> tag sounds like a good idea.
I have uploaded some css/js files to the trunk for some testing, and I'm
sending two patches for common.dtd and common.xsl (in the style/ and
style/xsl directories) so people that wish can try out this solution and
give some feedback to the proposition.
The changes will allow for syntax highlighting of C, Perl, Python and
shell scripts using something similar to this:
<highlight language="perl">
print($foo, $bar);
</highlight>
Any new languages we wish to add can be done so dynamically, as the
scripts are loaded according to which languages are put into the
<highlight> tags.
With regards,
Daniel.
Re: Syntax Highlighting
Posted by André Malo <nd...@perlig.de>.
> 1) Modify common.dtd to allow classes inside <pre> tags
> 2) Modify common.xsl to include the style sheet and scripts used for
> highlighting the source code examples in our documentation.
>
> To create syntax highlighted source code examples, the only requirement
> would be that you use the following syntax:
>
> <pre class="sh_c">
> code_goes_here(foo);
> </pre>
I'd prefer a different element on xml side. Like <highlight language="perl">
or <syntax>.
Otherwise I like the javascript solution.
nd
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Syntax Highlighting
Posted by Rich Bowen <rb...@rcbowen.com>.
>>
> The specific highlighter I chose (mainly because it is quite lightweight
> compared to some other solutions) is SHJS, which also supports well, any
> language you may want to highlight. For a specific list, you can view it
> at http://shjs.sourceforge.net/ - adding a new language is as simple as
> including one of the language files in our documents (
> http://shjs.sourceforge.net/lang/ ) and, for example to highlight Perl
> scripts, use:
> <pre class="sh_perl">
> print($foo, $bar);
> </pre>
So, it doesn't currently support httpd syntax, but could be persuaded to probably. Looking at the code ...
--
Rich Bowen
rbowen@rcbowen.com :: @rbowen
rbowen@apache.org
Re: Syntax Highlighting
Posted by Rich Bowen <rb...@rcbowen.com>.
On Apr 24, 2012, at 9:20 AM, Igor Galić wrote:
> Cool. Should be easy enough to create our own then.
Yep. Syntax looks pretty simple. Just a bunch of regexes mapped to styles. Should be fairly easy to create a httpd.conf mapping.
--
Rich Bowen
rbowen@rcbowen.com :: @rbowen
rbowen@apache.org
Re: Syntax Highlighting
Posted by Igor Galić <i....@brainsware.org>.
----- Original Message -----
> On 24-04-2012 14:31, Igor Galić wrote:
> >
> >> What other languages are available for syntax coloring? Trying to
> >> remember what other examples we might have in the docs. Perl, I
> >> expect.
> >
> > httpd.conf syntax hilighting would be a good thing to have.
> >
> >> --
> >> Rich Bowen
> >> rbowen@rcbowen.com :: @rbowen
> >> rbowen@apache.org
> >
> > i
> >
> The specific highlighter I chose (mainly because it is quite
> lightweight
> compared to some other solutions) is SHJS, which also supports well,
> any
> language you may want to highlight. For a specific list, you can view
> it
> at http://shjs.sourceforge.net/ - adding a new language is as simple
> as
> including one of the language files in our documents (
> http://shjs.sourceforge.net/lang/ ) and, for example to highlight
> Perl
> scripts, use:
> <pre class="sh_perl">
> print($foo, $bar);
> </pre>
Cool. Should be easy enough to create our own then.
> With regards,
> Daniel.
i
--
Igor Galić
Tel: +43 (0) 664 886 22 883
Mail: i.galic@brainsware.org
URL: http://brainsware.org/
GPG: 6880 4155 74BD FD7C B515 2EA5 4B1D 9E08 A097 C9AE
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Syntax Highlighting
Posted by Daniel Gruno <ru...@cord.dk>.
On 24-04-2012 14:31, Igor Galić wrote:
>
>> What other languages are available for syntax coloring? Trying to
>> remember what other examples we might have in the docs. Perl, I
>> expect.
>
> httpd.conf syntax hilighting would be a good thing to have.
>
>> --
>> Rich Bowen
>> rbowen@rcbowen.com :: @rbowen
>> rbowen@apache.org
>
> i
>
The specific highlighter I chose (mainly because it is quite lightweight
compared to some other solutions) is SHJS, which also supports well, any
language you may want to highlight. For a specific list, you can view it
at http://shjs.sourceforge.net/ - adding a new language is as simple as
including one of the language files in our documents (
http://shjs.sourceforge.net/lang/ ) and, for example to highlight Perl
scripts, use:
<pre class="sh_perl">
print($foo, $bar);
</pre>
With regards,
Daniel.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Syntax Highlighting
Posted by Igor Galić <i....@brainsware.org>.
> What other languages are available for syntax coloring? Trying to
> remember what other examples we might have in the docs. Perl, I
> expect.
httpd.conf syntax hilighting would be a good thing to have.
> --
> Rich Bowen
> rbowen@rcbowen.com :: @rbowen
> rbowen@apache.org
i
--
Igor Galić
Tel: +43 (0) 664 886 22 883
Mail: i.galic@brainsware.org
URL: http://brainsware.org/
GPG: 6880 4155 74BD FD7C B515 2EA5 4B1D 9E08 A097 C9AE
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Syntax Highlighting
Posted by Rich Bowen <rb...@rcbowen.com>.
On Apr 24, 2012, at 7:31 AM, Daniel Gruno wrote:
> After some fruitful discussions on IRC yesterday, I have tried out
> various ways of making syntax highlighting available for our
> documentation, and I've come across a method of doing so using
> JavaScript. The results seem to be very good, and before everybody runs
> away screaming because I mentioned the evil J-word, bear in mind that
> although this method requires a small fraction of a second to properly
> display the colors in your browser, it has the advantage of much smaller
> page sizes on our side, as we won't need to pre-pack our documents with
> a thousand class tags within each example source code.
>
> I have put up a test of highlighting using JS at
> http://www.humbedooh.com/apache/modguide.html.en which displays a
> similar result to what is achieved using the manual highlighting I have
> previously been using, with the added benefit of smaller size AND no
> more complaining from the build system that the XML is invalid, provided
> we adopt the following changes:
>
> 1) Modify common.dtd to allow classes inside <pre> tags
> 2) Modify common.xsl to include the style sheet and scripts used for
> highlighting the source code examples in our documentation.
>
> To create syntax highlighted source code examples, the only requirement
> would be that you use the following syntax:
>
> <pre class="sh_c">
> code_goes_here(foo);
> </pre>
A great big +1 to this in concept. At the very least, worth experimenting with in trunk. However, remember that the build stuff is the same in all branches, so changes affect everywhere.
What other languages are available for syntax coloring? Trying to remember what other examples we might have in the docs. Perl, I expect.
--
Rich Bowen
rbowen@rcbowen.com :: @rbowen
rbowen@apache.org
Re: Syntax Highlighting
Posted by Daniel Gruno <ru...@cord.dk>.
On 20-04-2012 14:49, Igor Galić wrote:
>
> Hey folks,
>
> for all those who haven't seen them yet, Daniel has started
> working on developer documentation:
>
> http://httpd.apache.org/docs/trunk/developer/modguide.html
>
> this also contains syntax highlighting.
> I'm a sucker for syntax highlighting, mostly because I couldn't
> survive without.
>
> If you've looked at the source code however...
>
> https://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/manual/developer/modguide.xml
>
> you'll notice that the current solution is sub-optimal.
> There are a lot of syntax-highlighters. enscript being the
> first to come to my mind.
>
> Does someone who know our docs-build system well enough
> to modify it so to automagickally highlight <example>
> sections? If not, maybe we could organize a session (on
> IRC) to do some reverse-engineering.
>
> In any case, we should document the process or the outcome,
> so those coming after us won't be put before the exact same
> problems.
>
> So long,
>
> i
>
After some fruitful discussions on IRC yesterday, I have tried out
various ways of making syntax highlighting available for our
documentation, and I've come across a method of doing so using
JavaScript. The results seem to be very good, and before everybody runs
away screaming because I mentioned the evil J-word, bear in mind that
although this method requires a small fraction of a second to properly
display the colors in your browser, it has the advantage of much smaller
page sizes on our side, as we won't need to pre-pack our documents with
a thousand class tags within each example source code.
I have put up a test of highlighting using JS at
http://www.humbedooh.com/apache/modguide.html.en which displays a
similar result to what is achieved using the manual highlighting I have
previously been using, with the added benefit of smaller size AND no
more complaining from the build system that the XML is invalid, provided
we adopt the following changes:
1) Modify common.dtd to allow classes inside <pre> tags
2) Modify common.xsl to include the style sheet and scripts used for
highlighting the source code examples in our documentation.
To create syntax highlighted source code examples, the only requirement
would be that you use the following syntax:
<pre class="sh_c">
code_goes_here(foo);
</pre>
As precedent, I can mention that the Apache Pivot project has been using
a similar method for a while.
I have the necessary patches at the ready, should people find this
solution viable. Please do respond with pluses and minuses or whichever
response you find appropriate.
With regards,
Daniel.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Syntax Highlighting
Posted by Daniel Gruno <ru...@cord.dk>.
On 20-04-2012 14:49, Igor Galić wrote:
>
> Hey folks,
>
> for all those who haven't seen them yet, Daniel has started
> working on developer documentation:
>
> http://httpd.apache.org/docs/trunk/developer/modguide.html
>
> this also contains syntax highlighting.
> I'm a sucker for syntax highlighting, mostly because I couldn't
> survive without.
>
> If you've looked at the source code however...
>
> https://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/manual/developer/modguide.xml
>
> you'll notice that the current solution is sub-optimal.
> There are a lot of syntax-highlighters. enscript being the
> first to come to my mind.
>
> Does someone who know our docs-build system well enough
> to modify it so to automagickally highlight <example>
> sections? If not, maybe we could organize a session (on
> IRC) to do some reverse-engineering.
>
> In any case, we should document the process or the outcome,
> so those coming after us won't be put before the exact same
> problems.
>
> So long,
>
> i
>
Yes, +1 (heck, +2) to this. Manually highlighting the examples is a pain
in the behind, especially when you make a mistake and you have to do it
all over again because you can't spot where to insert your corrected
lines due to all the <code> clutter.
I've tried looking at the XSLT stuff we use, but I just wound up being
even more confused. If there's anyone out there who can help, please,
please speak up :)
With regards,
Daniel.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org