You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs@httpd.apache.org by Luca Toscano <to...@gmail.com> on 2016/04/12 11:38:40 UTC
Proposal: add a permanent "Bugfix checklist" section to all manual pages
Hi docs@!
I have been thinking a way to inform users about our best practices when
finding inconsistencies in the docs, namely checking CHANGES and Bugzilla
first. Most of the times occasional users (or even experienced ones) tend
to forget where the changelog is, if httpd uses bugzilla or not, etc.. so
it would be great in my opinion to add a "reminder" in our manual pages.
The attached patch will add a little section in the right column (right
below "See also") to provide the aforementioned links.
Position, wording, etc.. can be changed of course, this email is only meant
to discuss the idea. If you don't like it, just state it out loud and I'll
drop it :)
Let me know your thoughts!
Luca
Re: Proposal: add a permanent "Bugfix checklist" section to all
manual pages
Posted by Luca Toscano <to...@gmail.com>.
Hi Christophe,
thanks for the feedback!
2016-04-12 18:57 GMT+02:00 Christophe JAILLET <christophe.jaillet@wanadoo.fr
>:
> Hi,
>
> I don't think it would be the right place for that.
> When I'm looking for some doc, I'm not looking for changelog or bug
> reports.
> I expect the doc to be up-to-date and to have compatibility notes when
> needed (new functionality, changed behavior...)
>
> Maybe an entry on the main page (http://httpd.apache.org/docs/2.4/) under
> "Release Notes" for a link to the changelog and another one under "Other
> Topics" for reporting something to bugzilla?
>
> More than that would display, IMHO, no that useful information.
>
> Just my 2 cents.
>
Adding some context about this idea: some days ago there was an email
thread in users@ about a strange behavior showed by the AllowOverrideList
directive, eventually turning up in a real bug. The documentation therefore
is consistent only from httpd version 2.4.20 onwards, and I wanted to add a
note to it (http://svn.apache.org/viewvc?view=revision&revision=1737382)
but I ended up putting it in the wrong place. Since the main takeaway was
to check CHANGES and bugzilla first, I wanted to add quicklinks for users
not familiar with them in a visible place. We can put it under a section in
http://httpd.apache.org/docs/2.4, but I would have preferred a more
recurrent and visible place.
"Compatibility" might be a better candidate as you pointed out! I checked
mod_core's documentation and indeed we have similar notes, even though this
one should look like "working only from version 2.18.20, that looks weird
to me.
Anyhow, good discussion, let's see if other people have comments!
Regards,
Luca
Re: Proposal: add a permanent "Bugfix checklist" section to all
manual pages
Posted by Rich Bowen <rb...@rcbowen.com>.
On 04/12/2016 12:57 PM, Christophe JAILLET wrote:
> Hi,
>
> I don't think it would be the right place for that.
> When I'm looking for some doc, I'm not looking for changelog or bug reports.
> I expect the doc to be up-to-date and to have compatibility notes when
> needed (new functionality, changed behavior...)
The trouble is that "up to date" means very different things for
different people. Folks that are running a third-party distribution of
the server often think that they are up to date when they are not, by
some other definition.
Based on conversations on IRC, and the kinds of questions people ask, I
think this would be really useful information.
>
> Maybe an entry on the main page (http://httpd.apache.org/docs/2.4/)
> under "Release Notes" for a link to the changelog and another one under
> "Other Topics" for reporting something to bugzilla?
>
> More than that would display, IMHO, no that useful information.
>
> Just my 2 cents.
>
> CJ
>
> Le 12/04/2016 11:38, Luca Toscano a écrit :
>> Hi docs@!
>>
>> I have been thinking a way to inform users about our best practices
>> when finding inconsistencies in the docs, namely checking CHANGES and
>> Bugzilla first. Most of the times occasional users (or even
>> experienced ones) tend to forget where the changelog is, if httpd uses
>> bugzilla or not, etc.. so it would be great in my opinion to add a
>> "reminder" in our manual pages. The attached patch will add a little
>> section in the right column (right below "See also") to provide the
>> aforementioned links.
>>
>> Position, wording, etc.. can be changed of course, this email is only
>> meant to discuss the idea. If you don't like it, just state it out
>> loud and I'll drop it :)
>>
>> Let me know your thoughts!
>>
>> Luca
>>
>>
>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail:docs-unsubscribe@httpd.apache.org
>> For additional commands, e-mail:docs-help@httpd.apache.org
>
--
Rich Bowen - rbowen@rcbowen.com - @rbowen
http://apachecon.com/ - @apachecon
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Proposal: add a permanent "Bugfix checklist" section to all
manual pages
Posted by Christophe JAILLET <ch...@wanadoo.fr>.
Hi,
I don't think it would be the right place for that.
When I'm looking for some doc, I'm not looking for changelog or bug reports.
I expect the doc to be up-to-date and to have compatibility notes when
needed (new functionality, changed behavior...)
Maybe an entry on the main page (http://httpd.apache.org/docs/2.4/)
under "Release Notes" for a link to the changelog and another one under
"Other Topics" for reporting something to bugzilla?
More than that would display, IMHO, no that useful information.
Just my 2 cents.
CJ
Le 12/04/2016 11:38, Luca Toscano a écrit :
> Hi docs@!
>
> I have been thinking a way to inform users about our best practices
> when finding inconsistencies in the docs, namely checking CHANGES and
> Bugzilla first. Most of the times occasional users (or even
> experienced ones) tend to forget where the changelog is, if httpd uses
> bugzilla or not, etc.. so it would be great in my opinion to add a
> "reminder" in our manual pages. The attached patch will add a little
> section in the right column (right below "See also") to provide the
> aforementioned links.
>
> Position, wording, etc.. can be changed of course, this email is only
> meant to discuss the idea. If you don't like it, just state it out
> loud and I'll drop it :)
>
> Let me know your thoughts!
>
> Luca
>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
> For additional commands, e-mail: docs-help@httpd.apache.org
Re: Proposal: add a permanent "Bugfix checklist" section to all
manual pages
Posted by Rich Bowen <rb...@rcbowen.com>.
On 04/26/2016 03:08 AM, Luca Toscano wrote:
> --- Why is HTTPD in capitals ? It's written httpd in whole doc ?
>
>
> IIRC was asked on IRC as way to put the HTTPD name in evidence and to be
> more consistent with naming across the docs, but I have to admit that I
> haven't checked very carefully and it might be a very good point to
> switch to 'httpd'. Any suggestion?
I believe that if you look through the archives, you'll find that Roy
has definite opinions on this. :-)
httpd is the name of the executable file.
The project is named 'The Apache HTTP Server Project' according to the
main website. Also:
The Apache HTTP Server ("httpd")
and
Apache httpd
I don't think we use HTTPD anywhere. Also, don't use HTTPd. That's just
poking the bear.
--
Rich Bowen - rbowen@rcbowen.com - @rbowen
http://apachecon.com/ - @apachecon
Re: Proposal: add a permanent "Bugfix checklist" section to all
manual pages
Posted by Luca Toscano <to...@gmail.com>.
2016-04-29 9:10 GMT+02:00 Lucien Gentis <lu...@univ-lorraine.fr>:
> but perhaps "Doc Feedback" instead of "Comments" . . .
>
> (this could decrease the number of Q/A comments)
>
I would prefer to keep Comments since it is easier to read, plus we have a
big warning about Q/A comments that is often not considered :(
>
> Le 28/04/2016 à 20:52, Christophe JAILLET a écrit :
>
> Le 28/04/2016 à 09:44, Luca Toscano a écrit :
>
>
>
> 2016-04-27 14:49 GMT+02:00 Eric Covener <co...@gmail.com>:
>
>> On Wed, Apr 27, 2016 at 7:43 AM, Lucien Gentis
>> <lu...@univ-lorraine.fr> wrote:
>> > I think of something like "Comments about this doc", since these are
>> only
>> > comments about the doc.
>>
>> Doc Feedback? I think space is at a premium in that sidebar.
>>
>>
> One solution could be http://apaste.info/IyX
>
> The "See also" section at the moment is only visualized if some document
> is linked in a xml file, but it could be displayed also if only the
> comments are present. This will avoid the creation of a new title/section
> in the right panel and will fix the visual inconsistency of the comments in
> all the doc pages.
>
> Let me know!
>
> Luca
>
> +1 for displaying "See also" all the time and having "Comment" in it.
>
>
Done! At this point, I think that the whole change (several commits) can be
backported to 2.4, but I'll wait a couple of days to let it boil in trunk.
Thanks a lot for all the feedbacks! I really like the fact that this change
has been shaped by a very active docs mailing list :)
Luca
Re: Proposal: add a permanent "Bugfix checklist" section to all
manual pages
Posted by Lucien Gentis <lu...@univ-lorraine.fr>.
but perhaps "Doc Feedback" instead of "Comments" . . .
(this could decrease the number of Q/A comments)
Le 28/04/2016 à 20:52, Christophe JAILLET a écrit :
> Le 28/04/2016 à 09:44, Luca Toscano a écrit :
>>
>>
>> 2016-04-27 14:49 GMT+02:00 Eric Covener <covener@gmail.com
>> <ma...@gmail.com>>:
>>
>> On Wed, Apr 27, 2016 at 7:43 AM, Lucien Gentis
>> <lucien.gentis@univ-lorraine.fr
>> <ma...@univ-lorraine.fr>> wrote:
>> > I think of something like "Comments about this doc", since
>> these are only
>> > comments about the doc.
>>
>> Doc Feedback? I think space is at a premium in that sidebar.
>>
>>
>> One solution could be http://apaste.info/IyX
>>
>> The "See also" section at the moment is only visualized if some
>> document is linked in a xml file, but it could be displayed also if
>> only the comments are present. This will avoid the creation of a new
>> title/section in the right panel and will fix the visual
>> inconsistency of the comments in all the doc pages.
>>
>> Let me know!
>>
>> Luca
>>
> +1 for displaying "See also" all the time and having "Comment" in it.
>
> CJ
>
--
Lucien GENTIS
UNIVERSITE DE LORRAINE - ESPE
Centre de Ressources Informatiques
5, Rue Paul Richard
C.O. 3 - MAXEVILLE
54528 LAXOU-CEDEX
Tél. 03 72 74 13 28
Email : lucien.gentis@univ-lorraine.fr
Re: Proposal: add a permanent "Bugfix checklist" section to all
manual pages
Posted by Christophe JAILLET <ch...@wanadoo.fr>.
Le 28/04/2016 à 09:44, Luca Toscano a écrit :
>
>
> 2016-04-27 14:49 GMT+02:00 Eric Covener <covener@gmail.com
> <ma...@gmail.com>>:
>
> On Wed, Apr 27, 2016 at 7:43 AM, Lucien Gentis
> <lucien.gentis@univ-lorraine.fr
> <ma...@univ-lorraine.fr>> wrote:
> > I think of something like "Comments about this doc", since these
> are only
> > comments about the doc.
>
> Doc Feedback? I think space is at a premium in that sidebar.
>
>
> One solution could be http://apaste.info/IyX
>
> The "See also" section at the moment is only visualized if some
> document is linked in a xml file, but it could be displayed also if
> only the comments are present. This will avoid the creation of a new
> title/section in the right panel and will fix the visual inconsistency
> of the comments in all the doc pages.
>
> Let me know!
>
> Luca
>
+1 for displaying "See also" all the time and having "Comment" in it.
CJ
Re: Proposal: add a permanent "Bugfix checklist" section to all
manual pages
Posted by Luca Toscano <to...@gmail.com>.
2016-04-27 14:49 GMT+02:00 Eric Covener <co...@gmail.com>:
> On Wed, Apr 27, 2016 at 7:43 AM, Lucien Gentis
> <lu...@univ-lorraine.fr> wrote:
> > I think of something like "Comments about this doc", since these are only
> > comments about the doc.
>
> Doc Feedback? I think space is at a premium in that sidebar.
>
>
One solution could be http://apaste.info/IyX
The "See also" section at the moment is only visualized if some document
is linked in a xml file, but it could be displayed also if only the
comments are present. This will avoid the creation of a new title/section
in the right panel and will fix the visual inconsistency of the comments in
all the doc pages.
Let me know!
Luca
Re: Proposal: add a permanent "Bugfix checklist" section to all
manual pages
Posted by Eric Covener <co...@gmail.com>.
On Wed, Apr 27, 2016 at 7:43 AM, Lucien Gentis
<lu...@univ-lorraine.fr> wrote:
> I think of something like "Comments about this doc", since these are only
> comments about the doc.
Doc Feedback? I think space is at a premium in that sidebar.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Proposal: add a permanent "Bugfix checklist" section to all
manual pages
Posted by Lucien Gentis <lu...@univ-lorraine.fr>.
I think of something like "Comments about this doc", since these are
only comments about the doc.
Le 27/04/2016 à 12:30, Luca Toscano a écrit :
>
>
> 2016-04-26 10:08 GMT+02:00 Luca Toscano <toscano.luca@gmail.com
> <ma...@gmail.com>>:
>
>
>
> 2016-04-26 9:08 GMT+02:00 Lucien Gentis
> <lucien.gentis@univ-lorraine.fr
> <ma...@univ-lorraine.fr>>:
>
> --- In mod_lua, "Comments" appears as an item of "Bugfix
> checklist", but in event, it appears as an item of "See also"
>
>
> Very good point, I noticed the same inconsistency. This is due to
> the fact that sometimes comments are under See Also, meanwhile
> other times are left alone. I thought it was clear with the extra
> space that comments wasn't belonging to the Bugfix checklist, but
> there is definitely the space for some extra improvement in the
> doc. What do you think about fixing this as follow up?
>
>
> I found the problem, that should lie among the following lines:
>
> http://apaste.info/4Kx (synopsis.xml)
>
> The comments link belongs to nothing and gets visually merged with
> whatever is rendered on top. We could think about adding a new title
> (like Bugfix checklist) before Comments named "Community feedback" or
> something similar to make everything more consistent.
>
> Thoughts?
>
> Luca
>
>
>
--
Lucien GENTIS
UNIVERSITE DE LORRAINE - ESPE
Centre de Ressources Informatiques
5, Rue Paul Richard
C.O. 3 - MAXEVILLE
54528 LAXOU-CEDEX
Tél. 03 72 74 13 28
Email : lucien.gentis@univ-lorraine.fr
Re: Proposal: add a permanent "Bugfix checklist" section to all
manual pages
Posted by Luca Toscano <to...@gmail.com>.
2016-04-26 10:08 GMT+02:00 Luca Toscano <to...@gmail.com>:
>
>
> 2016-04-26 9:08 GMT+02:00 Lucien Gentis <lu...@univ-lorraine.fr>:
>
>
>> --- In mod_lua, "Comments" appears as an item of "Bugfix checklist", but
>> in event, it appears as an item of "See also"
>
>
> Very good point, I noticed the same inconsistency. This is due to the fact
> that sometimes comments are under See Also, meanwhile other times are left
> alone. I thought it was clear with the extra space that comments wasn't
> belonging to the Bugfix checklist, but there is definitely the space for
> some extra improvement in the doc. What do you think about fixing this as
> follow up?
>
I found the problem, that should lie among the following lines:
http://apaste.info/4Kx (synopsis.xml)
The comments link belongs to nothing and gets visually merged with whatever
is rendered on top. We could think about adding a new title (like Bugfix
checklist) before Comments named "Community feedback" or something similar
to make everything more consistent.
Thoughts?
Luca
Re: Proposal: add a permanent "Bugfix checklist" section to all
manual pages
Posted by Luca Toscano <to...@gmail.com>.
2016-04-26 9:08 GMT+02:00 Lucien Gentis <lu...@univ-lorraine.fr>:
>
>
> Le 25/04/2016 13:49, Rich Bowen a écrit :
>
>> This is great. And it'll have the side-effect that it's likely to help
>> us identify issues that have been open for ages and are either already
>> addressed, or could be addressed.
>>
>> Thanks,
>>
>> On 04/24/2016 05:18 PM, Luca Toscano wrote:
>>
>>> New version just committed, examples:
>>>
>>> https://httpd.apache.org/docs/trunk/mod/mod_lua.html
>>> https://httpd.apache.org/docs/trunk/mod/event.html
>>>
>>>
> Nice thing !
>
> User has yet direct link to known issues, and new bug opening.
>
> Just little remarks :
>
> --- Why is HTTPD in capitals ? It's written httpd in whole doc ?
>
IIRC was asked on IRC as way to put the HTTPD name in evidence and to be
more consistent with naming across the docs, but I have to admit that I
haven't checked very carefully and it might be a very good point to switch
to 'httpd'. Any suggestion?
> --- "Bugfix checklist" panel does not appear in translated pages. Perhaps
> it's still to come ?
>
This is probably my fault, I modified only the style/lang/* files and the
synopsis.xsl thinking that it would have been enough. Am I missing
something?
> --- In mod_lua, "Comments" appears as an item of "Bugfix checklist", but
> in event, it appears as an item of "See also"
Very good point, I noticed the same inconsistency. This is due to the fact
that sometimes comments are under See Also, meanwhile other times are left
alone. I thought it was clear with the extra space that comments wasn't
belonging to the Bugfix checklist, but there is definitely the space for
some extra improvement in the doc. What do you think about fixing this as
follow up?
Thanks a lot for the feedback!
Luca
Re: Proposal: add a permanent "Bugfix checklist" section to all
manual pages
Posted by Lucien Gentis <lu...@univ-lorraine.fr>.
Le 25/04/2016 13:49, Rich Bowen a écrit :
> This is great. And it'll have the side-effect that it's likely to help
> us identify issues that have been open for ages and are either already
> addressed, or could be addressed.
>
> Thanks,
>
> On 04/24/2016 05:18 PM, Luca Toscano wrote:
>> New version just committed, examples:
>>
>> https://httpd.apache.org/docs/trunk/mod/mod_lua.html
>> https://httpd.apache.org/docs/trunk/mod/event.html
>>
Nice thing !
User has yet direct link to known issues, and new bug opening.
Just little remarks :
--- Why is HTTPD in capitals ? It's written httpd in whole doc ?
--- "Bugfix checklist" panel does not appear in translated pages.
Perhaps it's still to come ?
--- In mod_lua, "Comments" appears as an item of "Bugfix checklist", but
in event, it appears as an item of "See also"
Lucien
--
Lucien GENTIS
UNIVERSITE DE LORRAINE - ESPE
Centre de Ressources Informatiques
5, Rue Paul Richard
C.O. 3 - MAXEVILLE
54528 LAXOU-CEDEX
Tél. 03 72 74 13 28
Email :lucien.gentis@univ-lorraine.fr
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Proposal: add a permanent "Bugfix checklist" section to all
manual pages
Posted by Rich Bowen <rb...@rcbowen.com>.
This is great. And it'll have the side-effect that it's likely to help
us identify issues that have been open for ages and are either already
addressed, or could be addressed.
Thanks,
On 04/24/2016 05:18 PM, Luca Toscano wrote:
>
>
> New version just committed, examples:
>
> https://httpd.apache.org/docs/trunk/mod/mod_lua.html
> https://httpd.apache.org/docs/trunk/mod/event.html
>
--
Rich Bowen - rbowen@rcbowen.com - @rbowen
http://apachecon.com/ - @apachecon
Re: Proposal: add a permanent "Bugfix checklist" section to all
manual pages
Posted by Luca Toscano <to...@gmail.com>.
2016-04-25 21:23 GMT+02:00 Christophe JAILLET <christophe.jaillet@wanadoo.fr
>:
> Le 24/04/2016 à 23:18, Luca Toscano a écrit :
>
>
> New version just committed, examples:
>
> https://httpd.apache.org/docs/trunk/mod/mod_lua.html
> https://httpd.apache.org/docs/trunk/mod/event.html
>
> Luca
>
>
> You could help even more bug-report with something like:
>
> https://bz.apache.org/bugzilla/enter_bug.cgi?component=mod_lua&product=Apache%20httpd-2
> ^^^^^^^^^^^^^^^^^^
>
> with the same trick already used for bugzilla filtering.
>
>
> Also, I wouldn't add ":" at the end of "Bugfix checklist:"
>
>
> +1 for both, I will try to add the suggested changes today!
Thanks!
Luca
Re: Proposal: add a permanent "Bugfix checklist" section to all
manual pages
Posted by Christophe JAILLET <ch...@wanadoo.fr>.
Le 24/04/2016 à 23:18, Luca Toscano a écrit :
>
> New version just committed, examples:
>
> https://httpd.apache.org/docs/trunk/mod/mod_lua.html
> https://httpd.apache.org/docs/trunk/mod/event.html
>
> Luca
>
>
You could help even more bug-report with something like:
https://bz.apache.org/bugzilla/enter_bug.cgi?component=mod_lua&product=Apache%20httpd-2
^^^^^^^^^^^^^^^^^^
with the same trick already used for bugzilla filtering.
Also, I wouldn't add ":" at the end of "Bugfix checklist:"
CJ
Re: Proposal: add a permanent "Bugfix checklist" section to all
manual pages
Posted by Luca Toscano <to...@gmail.com>.
2016-04-22 8:19 GMT+02:00 Luca Toscano <to...@gmail.com>:
> +docs@
>
> 2016-04-20 23:25 GMT+02:00 Marion & Christophe JAILLET <
> christophe.jaillet@wanadoo.fr>:
>
>> Le 20/04/2016 19:37, Luca Toscano a écrit :
>>
>>
>>
>> 2016-04-18 21:46 GMT+02:00 Luca Toscano <to...@gmail.com>:
>>
>>>
>>>
>>> 2016-04-12 11:38 GMT+02:00 Luca Toscano < <to...@gmail.com>
>>> toscano.luca@gmail.com>:
>>>
>>>> Hi docs@!
>>>>
>>>> I have been thinking a way to inform users about our best practices
>>>> when finding inconsistencies in the docs, namely checking CHANGES and
>>>> Bugzilla first. Most of the times occasional users (or even experienced
>>>> ones) tend to forget where the changelog is, if httpd uses bugzilla or not,
>>>> etc.. so it would be great in my opinion to add a "reminder" in our manual
>>>> pages. The attached patch will add a little section in the right column
>>>> (right below "See also") to provide the aforementioned links.
>>>>
>>>> Position, wording, etc.. can be changed of course, this email is only
>>>> meant to discuss the idea. If you don't like it, just state it out loud and
>>>> I'll drop it :)
>>>>
>>>> Let me know your thoughts!
>>>>
>>>> Luca
>>>>
>>>>
>>> Restarted from the first email to avoid a quoting mess. I attached the
>>> final patch that would basically add the "Bugfix checklist" section before
>>> "see also" on each module's page. I wanted to restrict the scope of this
>>> patch to the places in which occasional users will benefit more rather than
>>> adding it to the whole documentation.
>>>
>>> Christophe, André, Rich: if you want to review the patch it would be
>>> really great. If anybody feels very strong against it I'll drop it.
>>>
>>
>> Committed in trunk, you can see some examples in:
>>
>> https://httpd.apache.org/docs/trunk/mod/event.html
>> https://httpd.apache.org/docs/trunk/mod/mod_lua.html
>>
>> Some comments made so far:
>>
>> - add the module's name to the bugzilla link (Open bugs) to visualize
>> only relevant bugs
>>
>> +1
>> Having a link that shows 1567 bugs, some opened in 2004 is just bad, IMHO.
>> But having, from the doc, a link to only corresponding items would be,
>> still IMHO, great.
>>
>
> I agree, the list of 1567 bugs is bad but at least it was a starting point
> to let the user know about bugzilla and what to set in the search bar to
> find the httpd bugs (I know straightforward but still..). Thanks to Jacob
> Champion I have a working version that produces links for modules only
> (using {name} in the xsl), but I need to resolve a couple of issues:
>
> 1) doc pages like "event" are tagged as "mpm_event" in bugzilla, but the
> {name} is event. So I'll need to check corner cases and evaluate some
> workaround to make everything works correctly. Don't expect to be a lot of
> work.
>
> 2) make sure that all the modules have a related component in bugzilla.
>
>
>> - move Httpd to HTTPD
>>
>> Having it consistent in the doc would indeed be nice. (we currently have
>> many ways to give the name of our web server)
>>
>
> Definitely, I thought that Httpd was fine but HTTPD sounds better.
>
>
>>
>>
>> - think about moving "Bugfix checkilist" to "Developer Resources" (still
>> thinking about this one because I'd like to keep something that connect the
>> user looking for a bug to these links).
>>
>> Or maybe just remove the tittle and move it just before "Comment"?
>>
>
> Could be an option, I wanted to display something that connects the
> thought of "ah httpd has a bug!" with "ah I need to check this link
> probably" while browsing a doc page. We'll see, the final version is far
> from complete!
>
>
>> Maybe, use httpd.docs entity instead of hard coded 2.4 (or equivalent)
>> and maybe even have a special case for trunk (link not displayed? Link to
>> 2.4 CHANGES?)
>>
>> Linking to http://httpd.apache.org/dev/dist/ may be bad. Are we sure
>> that this folder always have a CHANGES_2.4 file? What about trunk doc? (or
>> even 2.2 ?)
>> Maybe http://www.apache.org/dist/httpd/CHANGED_2.<version> would be
>> better (this is the one used on the main httpd.a.o page)
>>
>
> You are completely right, I will study a better solution. The initial
> thought was to avoid applying the change to 2.2 concentrating on 2.4, this
> is why I have hardcoded.
>
>
>>
>> Maybe "Known issues" would be better that "open(ed) bugs" ?
>>
>
> +1
>
>
>>
>> While at it, maybe add a link to report a bug fir this module ?
>>
>
> +1 great idea!
>
> Thanks a lot for the great feedback! Really appreciated! I'll start
> working on your suggestion as soon as possible and report back to this
> thread once I'll have an update :)
>
>
New version just committed, examples:
https://httpd.apache.org/docs/trunk/mod/mod_lua.html
https://httpd.apache.org/docs/trunk/mod/event.html
Luca
Re: Proposal: add a permanent "Bugfix checklist" section to all
manual pages
Posted by Luca Toscano <to...@gmail.com>.
+docs@
2016-04-20 23:25 GMT+02:00 Marion & Christophe JAILLET <
christophe.jaillet@wanadoo.fr>:
> Le 20/04/2016 19:37, Luca Toscano a écrit :
>
>
>
> 2016-04-18 21:46 GMT+02:00 Luca Toscano <to...@gmail.com>:
>
>>
>>
>> 2016-04-12 11:38 GMT+02:00 Luca Toscano < <to...@gmail.com>
>> toscano.luca@gmail.com>:
>>
>>> Hi docs@!
>>>
>>> I have been thinking a way to inform users about our best practices when
>>> finding inconsistencies in the docs, namely checking CHANGES and Bugzilla
>>> first. Most of the times occasional users (or even experienced ones) tend
>>> to forget where the changelog is, if httpd uses bugzilla or not, etc.. so
>>> it would be great in my opinion to add a "reminder" in our manual pages.
>>> The attached patch will add a little section in the right column (right
>>> below "See also") to provide the aforementioned links.
>>>
>>> Position, wording, etc.. can be changed of course, this email is only
>>> meant to discuss the idea. If you don't like it, just state it out loud and
>>> I'll drop it :)
>>>
>>> Let me know your thoughts!
>>>
>>> Luca
>>>
>>>
>> Restarted from the first email to avoid a quoting mess. I attached the
>> final patch that would basically add the "Bugfix checklist" section before
>> "see also" on each module's page. I wanted to restrict the scope of this
>> patch to the places in which occasional users will benefit more rather than
>> adding it to the whole documentation.
>>
>> Christophe, André, Rich: if you want to review the patch it would be
>> really great. If anybody feels very strong against it I'll drop it.
>>
>
> Committed in trunk, you can see some examples in:
>
> https://httpd.apache.org/docs/trunk/mod/event.html
> https://httpd.apache.org/docs/trunk/mod/mod_lua.html
>
> Some comments made so far:
>
> - add the module's name to the bugzilla link (Open bugs) to visualize only
> relevant bugs
>
> +1
> Having a link that shows 1567 bugs, some opened in 2004 is just bad, IMHO.
> But having, from the doc, a link to only corresponding items would be,
> still IMHO, great.
>
I agree, the list of 1567 bugs is bad but at least it was a starting point
to let the user know about bugzilla and what to set in the search bar to
find the httpd bugs (I know straightforward but still..). Thanks to Jacob
Champion I have a working version that produces links for modules only
(using {name} in the xsl), but I need to resolve a couple of issues:
1) doc pages like "event" are tagged as "mpm_event" in bugzilla, but the
{name} is event. So I'll need to check corner cases and evaluate some
workaround to make everything works correctly. Don't expect to be a lot of
work.
2) make sure that all the modules have a related component in bugzilla.
> - move Httpd to HTTPD
>
> Having it consistent in the doc would indeed be nice. (we currently have
> many ways to give the name of our web server)
>
Definitely, I thought that Httpd was fine but HTTPD sounds better.
>
>
> - think about moving "Bugfix checkilist" to "Developer Resources" (still
> thinking about this one because I'd like to keep something that connect the
> user looking for a bug to these links).
>
> Or maybe just remove the tittle and move it just before "Comment"?
>
Could be an option, I wanted to display something that connects the thought
of "ah httpd has a bug!" with "ah I need to check this link probably" while
browsing a doc page. We'll see, the final version is far from complete!
> Maybe, use httpd.docs entity instead of hard coded 2.4 (or equivalent) and
> maybe even have a special case for trunk (link not displayed? Link to 2.4
> CHANGES?)
>
> Linking to http://httpd.apache.org/dev/dist/ may be bad. Are we sure that
> this folder always have a CHANGES_2.4 file? What about trunk doc? (or even
> 2.2 ?)
> Maybe http://www.apache.org/dist/httpd/CHANGED_2.<version> would be
> better (this is the one used on the main httpd.a.o page)
>
You are completely right, I will study a better solution. The initial
thought was to avoid applying the change to 2.2 concentrating on 2.4, this
is why I have hardcoded.
>
> Maybe "Known issues" would be better that "open(ed) bugs" ?
>
+1
>
> While at it, maybe add a link to report a bug fir this module ?
>
+1 great idea!
Thanks a lot for the great feedback! Really appreciated! I'll start working
on your suggestion as soon as possible and report back to this thread once
I'll have an update :)
Luca
Re: Proposal: add a permanent "Bugfix checklist" section to all
manual pages
Posted by Luca Toscano <to...@gmail.com>.
2016-04-18 21:46 GMT+02:00 Luca Toscano <to...@gmail.com>:
>
>
> 2016-04-12 11:38 GMT+02:00 Luca Toscano <to...@gmail.com>:
>
>> Hi docs@!
>>
>> I have been thinking a way to inform users about our best practices when
>> finding inconsistencies in the docs, namely checking CHANGES and Bugzilla
>> first. Most of the times occasional users (or even experienced ones) tend
>> to forget where the changelog is, if httpd uses bugzilla or not, etc.. so
>> it would be great in my opinion to add a "reminder" in our manual pages.
>> The attached patch will add a little section in the right column (right
>> below "See also") to provide the aforementioned links.
>>
>> Position, wording, etc.. can be changed of course, this email is only
>> meant to discuss the idea. If you don't like it, just state it out loud and
>> I'll drop it :)
>>
>> Let me know your thoughts!
>>
>> Luca
>>
>>
> Restarted from the first email to avoid a quoting mess. I attached the
> final patch that would basically add the "Bugfix checklist" section before
> "see also" on each module's page. I wanted to restrict the scope of this
> patch to the places in which occasional users will benefit more rather than
> adding it to the whole documentation.
>
> Christophe, André, Rich: if you want to review the patch it would be
> really great. If anybody feels very strong against it I'll drop it.
>
Committed in trunk, you can see some examples in:
https://httpd.apache.org/docs/trunk/mod/event.html
https://httpd.apache.org/docs/trunk/mod/mod_lua.html
Some comments made so far:
- add the module's name to the bugzilla link (Open bugs) to visualize only
relevant bugs
- move Httpd to HTTPD
- think about moving "Bugfix checkilist" to "Developer Resources" (still
thinking about this one because I'd like to keep something that connect the
user looking for a bug to these links).
Any other feedback is welcome!
Luca
Re: Proposal: add a permanent "Bugfix checklist" section to all
manual pages
Posted by Rich Bowen <rb...@rcbowen.com>.
Please forgive me, I'm not ignoring you, just leading up to a major
conference tomorrow. I'll try to look at this in the airport today.
On Apr 18, 2016 3:46 PM, "Luca Toscano" <to...@gmail.com> wrote:
>
>
> 2016-04-12 11:38 GMT+02:00 Luca Toscano <to...@gmail.com>:
>
>> Hi docs@!
>>
>> I have been thinking a way to inform users about our best practices when
>> finding inconsistencies in the docs, namely checking CHANGES and Bugzilla
>> first. Most of the times occasional users (or even experienced ones) tend
>> to forget where the changelog is, if httpd uses bugzilla or not, etc.. so
>> it would be great in my opinion to add a "reminder" in our manual pages.
>> The attached patch will add a little section in the right column (right
>> below "See also") to provide the aforementioned links.
>>
>> Position, wording, etc.. can be changed of course, this email is only
>> meant to discuss the idea. If you don't like it, just state it out loud and
>> I'll drop it :)
>>
>> Let me know your thoughts!
>>
>> Luca
>>
>>
> Restarted from the first email to avoid a quoting mess. I attached the
> final patch that would basically add the "Bugfix checklist" section before
> "see also" on each module's page. I wanted to restrict the scope of this
> patch to the places in which occasional users will benefit more rather than
> adding it to the whole documentation.
>
> Christophe, André, Rich: if you want to review the patch it would be
> really great. If anybody feels very strong against it I'll drop it.
>
> Thanks!
>
> Luca
>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
> For additional commands, e-mail: docs-help@httpd.apache.org
>
Re: Proposal: add a permanent "Bugfix checklist" section to all
manual pages
Posted by Luca Toscano <to...@gmail.com>.
2016-04-12 11:38 GMT+02:00 Luca Toscano <to...@gmail.com>:
> Hi docs@!
>
> I have been thinking a way to inform users about our best practices when
> finding inconsistencies in the docs, namely checking CHANGES and Bugzilla
> first. Most of the times occasional users (or even experienced ones) tend
> to forget where the changelog is, if httpd uses bugzilla or not, etc.. so
> it would be great in my opinion to add a "reminder" in our manual pages.
> The attached patch will add a little section in the right column (right
> below "See also") to provide the aforementioned links.
>
> Position, wording, etc.. can be changed of course, this email is only
> meant to discuss the idea. If you don't like it, just state it out loud and
> I'll drop it :)
>
> Let me know your thoughts!
>
> Luca
>
>
Restarted from the first email to avoid a quoting mess. I attached the
final patch that would basically add the "Bugfix checklist" section before
"see also" on each module's page. I wanted to restrict the scope of this
patch to the places in which occasional users will benefit more rather than
adding it to the whole documentation.
Christophe, Andr茅, Rich: if you want to review the patch it would be really
great. If anybody feels very strong against it I'll drop it.
Thanks!
Luca
Re: Proposal: add a permanent "Bugfix checklist" section to all manual pages
Posted by André Malo <nd...@perlig.de>.
* Luca Toscano wrote:
> Hi André,
>
> Thanks for the feedback!
>
> 2016-04-12 14:53 GMT+02:00 André Malo <nd...@perlig.de>:
> > Hi Luca,
> >
> > * Luca Toscano wrote:
> > > Hi docs@!
> > >
> > > I have been thinking a way to inform users about our best practices
> > > when finding inconsistencies in the docs, namely checking CHANGES and
> > > Bugzilla first. Most of the times occasional users (or even experienced
> > > ones) tend to forget where the changelog is, if httpd uses bugzilla or
> > > not, etc.. so it would be great in my opinion to add a "reminder" in
> > > our manual pages. The attached patch will add a little section in the
> > > right column (right below "See also") to provide the aforementioned
> > > links.
> > >
> > > Position, wording, etc.. can be changed of course, this email is only
> >
> > meant
> >
> > > to discuss the idea. If you don't like it, just state it out loud and
> >
> > I'll
> >
> > > drop it :)
> >
> > I think, it's a good idea.
> >
> > Technical notes:
> >
> > - please separate space changes from functional changes
Your patch contained both formatting changes (removed trailing spaces)
and "real" changes. Please separate these kinds of changes (easier to
review).
Cheers,
nd
--
Real programmers confuse Christmas and Halloween because
DEC 25 = OCT 31. -- Unknown
(found in ssl_engine_mutex.c)
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Proposal: add a permanent "Bugfix checklist" section to all
manual pages
Posted by Luca Toscano <to...@gmail.com>.
Hi André,
Thanks for the feedback!
2016-04-12 14:53 GMT+02:00 André Malo <nd...@perlig.de>:
> Hi Luca,
>
> * Luca Toscano wrote:
>
> > Hi docs@!
> >
> > I have been thinking a way to inform users about our best practices when
> > finding inconsistencies in the docs, namely checking CHANGES and Bugzilla
> > first. Most of the times occasional users (or even experienced ones) tend
> > to forget where the changelog is, if httpd uses bugzilla or not, etc.. so
> > it would be great in my opinion to add a "reminder" in our manual pages.
> > The attached patch will add a little section in the right column (right
> > below "See also") to provide the aforementioned links.
> >
> > Position, wording, etc.. can be changed of course, this email is only
> meant
> > to discuss the idea. If you don't like it, just state it out loud and
> I'll
> > drop it :)
>
> I think, it's a good idea.
>
> Technical notes:
>
> - please separate space changes from functional changes
>
Not sure I follow this one, can you add a bit more info?
> - you need to put the message into all language files
>
Yep got it!
> - please use the version entities for the version
Ok!
Luca
Re: Proposal: add a permanent "Bugfix checklist" section to all manual pages
Posted by André Malo <nd...@perlig.de>.
Hi Luca,
* Luca Toscano wrote:
> Hi docs@!
>
> I have been thinking a way to inform users about our best practices when
> finding inconsistencies in the docs, namely checking CHANGES and Bugzilla
> first. Most of the times occasional users (or even experienced ones) tend
> to forget where the changelog is, if httpd uses bugzilla or not, etc.. so
> it would be great in my opinion to add a "reminder" in our manual pages.
> The attached patch will add a little section in the right column (right
> below "See also") to provide the aforementioned links.
>
> Position, wording, etc.. can be changed of course, this email is only meant
> to discuss the idea. If you don't like it, just state it out loud and I'll
> drop it :)
I think, it's a good idea.
Technical notes:
- please separate space changes from functional changes
- you need to put the message into all language files
- please use the version entities for the version
Thanks!
--
Already I've seen people (really!) write web URLs in the form:
http:\\some.site.somewhere
[...] How soon until greengrocers start writing "apples $1\pound"
or something? -- Joona I Palaste in clc
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
Re: Proposal: add a permanent "Bugfix checklist" section to all
manual pages
Posted by Rich Bowen <rb...@rcbowen.com>.
On 04/12/2016 05:38 AM, Luca Toscano wrote:
> Hi docs@!
>
> I have been thinking a way to inform users about our best practices when
> finding inconsistencies in the docs, namely checking CHANGES and
> Bugzilla first. Most of the times occasional users (or even experienced
> ones) tend to forget where the changelog is, if httpd uses bugzilla or
> not, etc.. so it would be great in my opinion to add a "reminder" in our
> manual pages. The attached patch will add a little section in the right
> column (right below "See also") to provide the aforementioned links.
I like this idea. Also, remember that people often read an individual
manual doc, completely out of context from the rest of the manual, and
so having useful "see also" links like this is hugely useful to, as you
say, occasional users.
>
> Position, wording, etc.. can be changed of course, this email is only
> meant to discuss the idea. If you don't like it, just state it out loud
> and I'll drop it :)
>
> Let me know your thoughts!
>
> Luca
>
>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
> For additional commands, e-mail: docs-help@httpd.apache.org
>
--
Rich Bowen - rbowen@rcbowen.com - @rbowen
http://apachecon.com/ - @apachecon
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org