Mailing List Archive: Apache: Docs

Syntax Highlighting, part 2

Index | Next | Previous | View Threaded

rumble at cord

May 1, 2012, 9:20 AM

Post #1 of 6 (123 views)
Permalink

Syntax Highlighting, part 2

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 [at] httpd
For additional commands, e-mail: docs-help [at] httpd

rbowen at rcbowen

May 2, 2012, 6:14 AM

Post #2 of 6 (115 views)
Permalink

Re: Syntax Highlighting, part 2 [In reply to]

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 [at] rcbowen :: @rbowen
rbowen [at] apache

DRuggeri at primary

May 2, 2012, 5:03 PM

Post #3 of 6 (114 views)
Permalink

Re: Syntax Highlighting, part 2 [In reply to]

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 [at] httpd
For additional commands, e-mail: docs-help [at] httpd

lucien.gentis at medecine

May 3, 2012, 6:49 AM

Post #4 of 6 (112 views)
Permalink

Re: Syntax Highlighting, part 2 [In reply to]

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 [at] httpd
> For additional commands, e-mail: docs-help [at] httpd
>
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 [at] httpd
For additional commands, e-mail: docs-help [at] httpd

rumble at cord

May 3, 2012, 6:58 AM

Post #5 of 6 (118 views)
Permalink

Re: Syntax Highlighting, part 2 [In reply to]

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 [at] httpd
> For additional commands, e-mail: docs-help [at] httpd
>

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 [at] httpd
For additional commands, e-mail: docs-help [at] httpd

i.galic at brainsware

May 3, 2012, 9:15 AM

Post #6 of 6 (113 views)
Permalink

Re: Syntax Highlighting, part 2 [In reply to]

----- 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 [at] httpd
> > For additional commands, e-mail: docs-help [at] httpd
> >
>
> 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 [at] brainsware
URL: http://brainsware.org/
GPG: 6880 4155 74BD FD7C B515 2EA5 4B1D 9E08 A097 C9AE

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

Index | Next | Previous | View Threaded

Interested in having your list archived? Contact Gossamer Threads