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

Mailing List Archive: Apache: Docs

Comments in docs

 

 

Apache docs RSS feed   Index | Next | Previous | View Threaded


rbowen at rcbowen

May 3, 2012, 6:54 AM

Post #1 of 23 (1691 views)
Permalink
Comments in docs

I've long been a fan of the PHP documentation - specifically, the way that they solicit commentary from readers, and then fold that commentary into the docs. Not only did it encourage me to comment on the docs, it also got me involved in the PHP documentation project, at least marginally. The barrier to entry is so low that all you have to do is be a writer.

As I've said elsewhere, our process seems to require that you be a programmer. I'd like to see what we can do to change that. This is why the docs@ list was split from the dev@ list in the first place. And it was at least in part why we started doing stuff in a wiki, although that hasn't been nearly as successful as I wished.

I'd like to brainstorm about how we can do something like the PHP docs - provide a way for end-users to comment on a given doc, and then have a process for moderating and folding those comments into the docs themselves.

The PHP docs team have offered us, on several occasions, their entire documentation infrastructure. I haven't even bothered to mention that to this list, because it would be an *enormous* change. I've discussed it in person with several docs folks, and the response has consistently been, yeah, that would be cool, but it's too big a change. But I'd be glad to have Phil write up something if people are at all interested.

I digress.

Does anyone know of a way to integrate a third-party comment service like, say, disqus or whatnot, into our docs, so that we could get direct feedback from our audience? Or can you think of another way that we might do this?

Shosholoza.

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


rumble at cord

May 3, 2012, 7:25 AM

Post #2 of 23 (1660 views)
Permalink
Re: Comments in docs [In reply to]

On 03-05-2012 15:54, Rich Bowen wrote:
> Does anyone know of a way to integrate a third-party comment service
> like, say, disqus or whatnot, into our docs, so that we could get direct
> feedback from our audience? Or can you think of another way that we
> might do this?
>

I like the general idea, but I'm unsure as to how we'd actually pull it
off. I'll do some experimentation on it during the weekend and see if
it'll actually make sense to me in our docs. If we could get the
necessary tools from infra to make it happen, then we could also
integrate it into the docs@ list with notifications when someone adds a
comment to a page, and thus quickly review new changes to the comments.

But, as said, I'll mull it over and see if I can work out a sensible
solution, and then get back to you on that.

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:06 AM

Post #3 of 23 (1653 views)
Permalink
Re: Comments in docs [In reply to]

----- Original Message -----
> On 03-05-2012 15:54, Rich Bowen wrote:
> > Does anyone know of a way to integrate a third-party comment
> > service
> > like, say, disqus or whatnot, into our docs, so that we could get
> > direct
> > feedback from our audience? Or can you think of another way that we
> > might do this?
> >
>
> I like the general idea, but I'm unsure as to how we'd actually pull
> it
> off. I'll do some experimentation on it during the weekend and see if
> it'll actually make sense to me in our docs. If we could get the
> necessary tools from infra to make it happen, then we could also
> integrate it into the docs@ list with notifications when someone adds
> a
> comment to a page, and thus quickly review new changes to the
> comments.
>
> But, as said, I'll mull it over and see if I can work out a sensible
> solution, and then get back to you on that.

I've heard a couple of people already drop the name of
disqus. Disqus should be fairly easy to include, as it
merely needs some JS - Just like the Syntax Highlighting
now does. It would offer a fairly unobtrusive way to
introduce comments. I've already talked to the disqus
folks (via twitter) about one of the most important
aspects: Comments are stored and retrieved from their
infra. That means we're not putting a burden on ours.

But who do they belong to?

https://twitter.com/#!/disqus/status/152560950174679040

They'd belong to "us", so that's a thing less to worry
about. I'd say a big +1 from me for experimenting with
this.

Please remember that there's an option to moderate
comments. I'd send new comments to docs@ for review/approval.
I don't know the exact workings of this, but if it's a
link to approve that would be not so good. With docs@
being a public ML and all..

> With regards,
> Daniel.

So long,

i

--
Igor Galić

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


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


niq at apache

May 3, 2012, 9:08 AM

Post #4 of 23 (1657 views)
Permalink
Re: Comments in docs [In reply to]

On 3 May 2012, at 14:54, Rich Bowen wrote:

> I've long been a fan of the PHP documentation - specifically, the way that they solicit commentary from readers, and then fold that commentary into the docs. Not only did it encourage me to comment on the docs, it also got me involved in the PHP documentation project, at least marginally. The barrier to entry is so low that all you have to do is be a writer.

I introduced a comment mechanism at apachetutor, only to find a predominance of spam over
anything worth having (a very occasional worthwhile comment or question that provoked me
to update something). There's also an annoying-spam issue on our httpd wiki.

How does PHP documentation deal with the problem of spam?

--
Nick Kew
---------------------------------------------------------------------
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:13 AM

Post #5 of 23 (1657 views)
Permalink
Re: Comments in docs [In reply to]

----- Original Message -----
>
> On 3 May 2012, at 14:54, Rich Bowen wrote:
>
> > I've long been a fan of the PHP documentation - specifically, the
> > way that they solicit commentary from readers, and then fold that
> > commentary into the docs. Not only did it encourage me to comment
> > on the docs, it also got me involved in the PHP documentation
> > project, at least marginally. The barrier to entry is so low that
> > all you have to do is be a writer.
>
> I introduced a comment mechanism at apachetutor, only to find a
> predominance of spam over
> anything worth having (a very occasional worthwhile comment or
> question that provoked me
> to update something). There's also an annoying-spam issue on our
> httpd wiki.
>
> How does PHP documentation deal with the problem of spam?

I don't know how PHP deals with spam, but disqus has a number
of ways:

http://docs.disqus.com/help/48/

> --
> Nick Kew

i

--
Igor Galić

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


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


rbowen at rcbowen

May 3, 2012, 9:20 AM

Post #6 of 23 (1660 views)
Permalink
Re: Comments in docs [In reply to]

On May 3, 2012, at 12:08 PM, Nick Kew wrote:

>>
>> I've long been a fan of the PHP documentation - specifically, the way that they solicit commentary from readers, and then fold that commentary into the docs. Not only did it encourage me to comment on the docs, it also got me involved in the PHP documentation project, at least marginally. The barrier to entry is so low that all you have to do is be a writer.
>
> I introduced a comment mechanism at apachetutor, only to find a predominance of spam over
> anything worth having (a very occasional worthwhile comment or question that provoked me
> to update something). There's also an annoying-spam issue on our httpd wiki.
>
> How does PHP documentation deal with the problem of spam?

I've noticed *very* little spam in the php docs. They have an "are you a human" type of math word problem that you have to answer. Like "What is five minus one". But they also moderate the comments as they come in, which is a thankless job. I think that it's worthwhile, but will require some folks volunteering to staff this. I volunteer.

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


rbowen at rcbowen

May 3, 2012, 9:21 AM

Post #7 of 23 (1658 views)
Permalink
Re: Comments in docs [In reply to]

On May 3, 2012, at 12:06 PM, Igor Galić wrote:

> Please remember that there's an option to moderate
> comments. I'd send new comments to docs@ for review/approval.
> I don't know the exact workings of this, but if it's a
> link to approve that would be not so good. With docs@
> being a public ML and all..

Eww. No. It needs to go to Yet Another ML, staffed by a few of us. Innundating docs@ would be a very, very bad thing.

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


i.galic at brainsware

May 3, 2012, 9:28 AM

Post #8 of 23 (1658 views)
Permalink
Re: Comments in docs [In reply to]

> > How does PHP documentation deal with the problem of spam?
>
[snip]
> "What is five minus one". But they also moderate the comments as
> they come in, which is a thankless job. I think that it's
> worthwhile, but will require some folks volunteering to staff this.
> I volunteer.

hmmm… just like supporting users@?
Yeah… probably just like that ;)
I suggest recruiting some volunteers from that pool.

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

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


rumble at cord

May 3, 2012, 9:55 AM

Post #9 of 23 (1658 views)
Permalink
Re: Comments in docs [In reply to]

On 03-05-2012 18:28, Igor Galić wrote:
>
>>> How does PHP documentation deal with the problem of spam?
>>
> [snip]
>> "What is five minus one". But they also moderate the comments as
>> they come in, which is a thankless job. I think that it's
>> worthwhile, but will require some folks volunteering to staff this.
>> I volunteer.
>
> hmmm… just like supporting users@?
> Yeah… probably just like that ;)
> I suggest recruiting some volunteers from that pool.
>

I'll gladly volunteer to do some grunt work on that list, but I'm a tiny
bit skeptic about simply recruiting off users@, since this stuff would
be a *part* of the documentation, and thus we'd need a bit more info
than just "I'm a users@ subscriber, lemme volunteer". Or maybe I'm just
being paranoid...who said that?!

Also, it would be nice to hear some suggestions from people as to what
they would prefer; Should we use an off-site provider like disqus, or
should we try to make something homebrewed where we can have config
syntax highlighting in the comments and so forth. And I don't know
exactly how it would work with an external provider and a private
mailing list hook, but maybe somebody else knows :)

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, 10:07 AM

Post #10 of 23 (1655 views)
Permalink
Re: Comments in docs [In reply to]

----- Original Message -----
> On 03-05-2012 18:28, Igor Galić wrote:
> >
> >>> How does PHP documentation deal with the problem of spam?
> >>
> > [snip]
> >> "What is five minus one". But they also moderate the comments as
> >> they come in, which is a thankless job. I think that it's
> >> worthwhile, but will require some folks volunteering to staff
> >> this.
> >> I volunteer.
> >
> > hmmm… just like supporting users@?
> > Yeah… probably just like that ;)
> > I suggest recruiting some volunteers from that pool.
> >
>
> I'll gladly volunteer to do some grunt work on that list, but I'm a
> tiny
> bit skeptic about simply recruiting off users@, since this stuff
> would
> be a *part* of the documentation, and thus we'd need a bit more info
> than just "I'm a users@ subscriber, lemme volunteer". Or maybe I'm
> just
> being paranoid...who said that?!

There's a simple way to find out if our volunteers from users@ are
any good: Check out their users@ history.

> Also, it would be nice to hear some suggestions from people as to
> what
> they would prefer; Should we use an off-site provider like disqus, or
> should we try to make something homebrewed where we can have config
> syntax highlighting in the comments and so forth. And I don't know

I'm pretty and sure that the disqus offers these things as well.
And while I know that it's not the Apache Way, because, it wasn't
invented here, I'm pretty sure it's a good idea to experiment with
something that already exists, because we invent and roll our own
wheel http://gallery.bomelakiesie.co.za/albums/funny/cisco_wheel.jpg

> exactly how it would work with an external provider and a private
> mailing list hook, but maybe somebody else knows :)

A list moderator can sign up an email to a list. Of course
most comment systems send out from funky email unique email
addresses that you can directly reply to for moderation..

So there's that.

But it's things we can find out. We don't have to endlessly
speculate about them.
We could just ask the actual disqus support!

If we decide we want to try to go in that direction, anyway.

> 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


rumble at cord

May 3, 2012, 12:55 PM

Post #11 of 23 (1645 views)
Permalink
Re: Comments in docs [In reply to]

On 03-05-2012 19:07, Igor Galić wrote:

> I'm pretty and sure that the disqus offers these things as well.
> And while I know that it's not the Apache Way, because, it wasn't
> invented here, I'm pretty sure it's a good idea to experiment with
> something that already exists, because we invent and roll our own
> wheel http://gallery.bomelakiesie.co.za/albums/funny/cisco_wheel.jpg


I've set up a small test for the Disqus way of approaching this subject,
located at the bottom of
http://www.humbedooh.com/apache/mod_asis.html.en - it actually
integrates quite well with the documentation.

As for moderations, we would have a lot of options, such as allowing
people to comment unmoderated, but require that comments with links in
them are approved first, or we could be as strict as possible and
require that everything gets approved before it's shown. There are also
some nice anti-spam features that allows us to control who gets to post
what and where, as well as threaded discussions, per-page discussions
and so forth and so forth.

Give it a test spin :) I'm liking it more and more.

With regards,
Daniel.

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


nd at perlig

May 3, 2012, 1:06 PM

Post #12 of 23 (1646 views)
Permalink
Re: Comments in docs [In reply to]

* Daniel Gruno wrote:

> On 03-05-2012 19:07, Igor Galić wrote:
> > I'm pretty and sure that the disqus offers these things as well.
> > And while I know that it's not the Apache Way, because, it wasn't
> > invented here, I'm pretty sure it's a good idea to experiment with
> > something that already exists, because we invent and roll our own
> > wheel http://gallery.bomelakiesie.co.za/albums/funny/cisco_wheel.jpg
>
> I've set up a small test for the Disqus way of approaching this subject,
> located at the bottom of
> http://www.humbedooh.com/apache/mod_asis.html.en - it actually
> integrates quite well with the documentation.
>
> As for moderations, we would have a lot of options, such as allowing
> people to comment unmoderated, but require that comments with links in
> them are approved first, or we could be as strict as possible and
> require that everything gets approved before it's shown. There are also
> some nice anti-spam features that allows us to control who gets to post
> what and where, as well as threaded discussions, per-page discussions
> and so forth and so forth.
>
> Give it a test spin :) I'm liking it more and more.

Is it possible to integrate different languages? (And how do we moderate
those?)

nd
--
Flhacs wird im Usenet grundsätzlich alsfhc geschrieben. Schreibt man
lafhsc nicht slfach, so ist das schlichtweg hclafs. Hingegen darf man
rihctig ruhig rhitcgi schreiben, weil eine shcalfe Schreibweise bei
irhictg nicht als shflac angesehen wird. -- Hajo Pflüger in dnq

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


rumble at cord

May 3, 2012, 1:14 PM

Post #13 of 23 (1645 views)
Permalink
Re: Comments in docs [In reply to]

On 03-05-2012 22:06, André Malo wrote:

>
> Is it possible to integrate different languages? (And how do we moderate
> those?)
>
> nd

Yes, from what I have read about the embedded stuff so far, we can make
it distinguish between the various languages through the xslt by, for
example with the French version, setting the JavaScript variable
disqus_url to windows.location.href + '.fr', which I'm sure we can yank
out of the transformations somehow.

With regards to moderating them all, I dunno...maybe it's best if we
just keep that specific part as one, unified English commentary section,
both for the sake of moderating properly, but also for sharing
experiences across nationalities and stubborn browser locales.


With regards,
Daniel.

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


rbowen at rcbowen

May 3, 2012, 1:17 PM

Post #14 of 23 (1643 views)
Permalink
Re: Comments in docs [In reply to]

>
> Is it possible to integrate different languages? (And how do we moderate
> those?)
>

I expect people can post in any language. We can then use google translate
to moderate them. That usually works well enough to understand the intent.


kyanha at kyanha

May 3, 2012, 5:13 PM

Post #15 of 23 (1637 views)
Permalink
Re: Comments in docs [In reply to]

On Thu, May 3, 2012 at 1:17 PM, Rich Bowen <rbowen [at] rcbowen> wrote:
>
>>
>> Is it possible to integrate different languages? (And how do we moderate
>> those?)
>>
>
> I expect people can post in any language. We can then use google translate
> to moderate them. That usually works well enough to understand the intent.

The best way to ensure that one has a useful Google translation is to substitute to the intended language, then translate back from the intended to the original language. If the idea translated back out is close to the intended statement, it's probably fine. If not, there will likely be major communications issues, and should be reworded.

To put this in practice while writing documentation comments, perhaps have a secondary window/iframe/whatever that shows the output of translating xx -> en -> xx. When the writer accepts it, save/post both the original xx and the en transform.

-Kyle H
Attachments: Verify This Message with Penango.p7s (5.96 KB)


rbowen at rcbowen

May 3, 2012, 6:02 PM

Post #16 of 23 (1640 views)
Permalink
Re: Comments in docs [In reply to]

On May 3, 2012, at 8:13 PM, Kyle Hamilton wrote:

>
> On Thu, May 3, 2012 at 1:17 PM, Rich Bowen <rbowen [at] rcbowen> wrote:
>>
>>>
>>> Is it possible to integrate different languages? (And how do we moderate
>>> those?)
>>>
>>
>> I expect people can post in any language. We can then use google translate
>> to moderate them. That usually works well enough to understand the intent.
>
> The best way to ensure that one has a useful Google translation is to substitute to the intended language, then translate back from the intended to the original language. If the idea translated back out is close to the intended statement, it's probably fine. If not, there will likely be major communications issues, and should be reworded.
>
> To put this in practice while writing documentation comments, perhaps have a secondary window/iframe/whatever that shows the output of translating xx -> en -> xx. When the writer accepts it, save/post both the original xx and the en transform.

The comments are not part of the documentation. They are comments. They may eventually result in changes to the documentation, but as a comment, they serve merely to start the conversation. That's why I thought that, in this context, an exact and grammatical translation wasn't critical.

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


rumble at cord

May 4, 2012, 1:51 AM

Post #17 of 23 (1640 views)
Permalink
Re: Comments in docs [In reply to]

On 04-05-2012 02:13, Kyle Hamilton wrote:
>
> On Thu, May 3, 2012 at 1:17 PM, Rich Bowen <rbowen [at] rcbowen> wrote:
>>
>>>
>>> Is it possible to integrate different languages? (And how do we moderate
>>> those?)
>>>
>>
>> I expect people can post in any language. We can then use google
>> translate
>> to moderate them. That usually works well enough to understand the
>> intent.

I have made the necessary changes to the XSL files in order to
incorporate this in trunk and give it a test spin on a select number of
documents. However, before we begin such, there are a few questions that
need answering:

1) Should each individual translation of a document have its own
comments, or should they be unified for the document as a whole? ie
should there be a French and an English comments thread, or should it
just be one big happy family?

2) I assume that current/ and 2.4/ should point to the same disqus ID,
but should trunk/ also point to the same, or should we keep those
discussions separate?

With regards,
Daniel.


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


nd at perlig

May 4, 2012, 1:55 AM

Post #18 of 23 (1641 views)
Permalink
Re: Comments in docs [In reply to]

On Thursday 03 May 2012 21:55:02 Daniel Gruno wrote:
> On 03-05-2012 19:07, Igor Galić wrote:
> > I'm pretty and sure that the disqus offers these things as well.
> > And while I know that it's not the Apache Way, because, it wasn't
> > invented here, I'm pretty sure it's a good idea to experiment with
> > something that already exists, because we invent and roll our own
> > wheel http://gallery.bomelakiesie.co.za/albums/funny/cisco_wheel.jpg
>
> I've set up a small test for the Disqus way of approaching this subject,
> located at the bottom of
> http://www.humbedooh.com/apache/mod_asis.html.en - it actually
> integrates quite well with the documentation.
>
> As for moderations, we would have a lot of options, such as allowing
> people to comment unmoderated, but require that comments with links in
> them are approved first, or we could be as strict as possible and
> require that everything gets approved before it's shown. There are also
> some nice anti-spam features that allows us to control who gets to post
> what and where, as well as threaded discussions, per-page discussions
> and so forth and so forth.
>
> Give it a test spin :) I'm liking it more and more.

Another side note:

We need to build a different version for online vs. shipped after integrating
comments. I don't think it's reasonable to burden the locally installed docs
with external references.

nd

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


rumble at cord

May 4, 2012, 2:18 AM

Post #19 of 23 (1638 views)
Permalink
Re: Comments in docs [In reply to]

On 04-05-2012 10:55, André Malo wrote:
>
> Another side note:
>
> We need to build a different version for online vs. shipped after integrating
> comments. I don't think it's reasonable to burden the locally installed docs
> with external references.
>
> nd
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docs-unsubscribe [at] httpd
> For additional commands, e-mail: docs-help [at] httpd
>

Yes, I added a test for "$is-chm or $is-zip or $metafile/basename =
'index'" so it would only add the comments for our online version and
only for non-index pages. And if I managed to screw that up, I'm hoping
you'll lend a hand at fixing it :)

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 4, 2012, 2:18 AM

Post #20 of 23 (1637 views)
Permalink
Re: Comments in docs [In reply to]

----- Original Message -----
> On Thursday 03 May 2012 21:55:02 Daniel Gruno wrote:
> > On 03-05-2012 19:07, Igor Galić wrote:
> > > I'm pretty and sure that the disqus offers these things as well.
> > > And while I know that it's not the Apache Way, because, it wasn't
> > > invented here, I'm pretty sure it's a good idea to experiment
> > > with
> > > something that already exists, because we invent and roll our own
> > > wheel
> > > http://gallery.bomelakiesie.co.za/albums/funny/cisco_wheel.jpg
> >
> > I've set up a small test for the Disqus way of approaching this
> > subject,
> > located at the bottom of
> > http://www.humbedooh.com/apache/mod_asis.html.en - it actually
> > integrates quite well with the documentation.
> >
> > As for moderations, we would have a lot of options, such as
> > allowing
> > people to comment unmoderated, but require that comments with links
> > in
> > them are approved first, or we could be as strict as possible and
> > require that everything gets approved before it's shown. There are
> > also
> > some nice anti-spam features that allows us to control who gets to
> > post
> > what and where, as well as threaded discussions, per-page
> > discussions
> > and so forth and so forth.
> >
> > Give it a test spin :) I'm liking it more and more.
>
> Another side note:
>
> We need to build a different version for online vs. shipped after
> integrating
> comments. I don't think it's reasonable to burden the locally
> installed docs
> with external references.

Some people may even prefer to have this online. PostgreSQL offers
static vs dynamic docs.

> nd

i

--
Igor Galić

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


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


nd at perlig

May 4, 2012, 2:39 AM

Post #21 of 23 (1637 views)
Permalink
Re: Comments in docs [In reply to]

> Yes, I added a test for "$is-chm or $is-zip or $metafile/basename =
> 'index'" so it would only add the comments for our online version and
> only for non-index pages. And if I managed to screw that up, I'm hoping
> you'll lend a hand at fixing it :)

;-)

That's not enough, unfortuantely. The production documentation is currently
shipped as-online; as part of the httpd tree. We need a separate tree for
that (then extending for different online versions as Igor suggests, will be
easy, I guess).

I'll give it a thought.

nd

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


rumble at cord

May 4, 2012, 2:48 AM

Post #22 of 23 (1639 views)
Permalink
Re: Comments in docs [In reply to]

On 04-05-2012 11:39, André Malo wrote:
>> Yes, I added a test for "$is-chm or $is-zip or $metafile/basename =
>> 'index'" so it would only add the comments for our online version and
>> only for non-index pages. And if I managed to screw that up, I'm hoping
>> you'll lend a hand at fixing it :)
>
> ;-)
>
> That's not enough, unfortuantely. The production documentation is currently
> shipped as-online; as part of the httpd tree. We need a separate tree for
> that (then extending for different online versions as Igor suggests, will be
> easy, I guess).
>
> I'll give it a thought.
>
> nd
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docs-unsubscribe [at] httpd
> For additional commands, e-mail: docs-help [at] httpd
>
On a separate note, to the best of my knowledge, even if the comment
section is visible in what we ship, the comments will not work when you
view it as an offline document or on any other server than httpd.a.o, it
will simply show "can't view comments, bla bla" in a small box at the
bottom.

Another solution would be to simply extend the javascript to simply not
try to render the comments unless window.location.href contains
httpd.apache.org. Thus, the "Comments" link will still be on the pages
in the quickview, but it won't show anything. Or it could possibly just
say "Comments disabled for offline viewing" or some such.

I will roll out the Disqus example on a single section at first, before
I commit the XSL changes and we have to rebuild 671 files and what not,
and as per Rich's suggestion, that section will be the rewrite guides in
trunk (I too have to see whether this actually works within the
httpd.a.o namespace before I can do any further work).

With regards,
Daniel.

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


nd at perlig

May 4, 2012, 3:09 AM

Post #23 of 23 (1639 views)
Permalink
Re: Comments in docs [In reply to]

On Friday 04 May 2012 11:48:01 Daniel Gruno wrote:
> On 04-05-2012 11:39, André Malo wrote:
> >> Yes, I added a test for "$is-chm or $is-zip or $metafile/basename =
> >> 'index'" so it would only add the comments for our online version and
> >> only for non-index pages. And if I managed to screw that up, I'm hoping
> >> you'll lend a hand at fixing it :)
> >
> > ;-)
> >
> > That's not enough, unfortuantely. The production documentation is
> > currently shipped as-online; as part of the httpd tree. We need a
> > separate tree for that (then extending for different online versions as
> > Igor suggests, will be easy, I guess).
> >
> > I'll give it a thought.
> >
> > nd

> On a separate note, to the best of my knowledge, even if the comment
> section is visible in what we ship, the comments will not work when you
> view it as an offline document or on any other server than httpd.a.o, it
> will simply show "can't view comments, bla bla" in a small box at the
> bottom.

Still an external reference. -> notgood.

> Another solution would be to simply extend the javascript to simply not
> try to render the comments unless window.location.href contains
> httpd.apache.org. Thus, the "Comments" link will still be on the pages
> in the quickview, but it won't show anything. Or it could possibly just
> say "Comments disabled for offline viewing" or some such.

that's better. But I still think, it's best to strip them. For practical
reasons it might be best here to build the shipped tree on releases anyway
(but xform mistakes [1] may get lost then).

> I will roll out the Disqus example on a single section at first, before
> I commit the XSL changes and we have to rebuild 671 files and what not,
> and as per Rich's suggestion, that section will be the rewrite guides in
> trunk (I too have to see whether this actually works within the
> httpd.a.o namespace before I can do any further work).

var lang = 'en';

needs to go below the script intro comment (which should be on the same line
as <script>), even better into the function. You can just close the CDATA,
add the language and open up a new one.

nd

[1] From time to time it happens for whatever reasons, that pages break (say,
the Korean files are not transformed correctly because the java installation
is missing stuff). Recently some files were just empty (checked in).

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

Apache docs RSS feed   Index | Next | Previous | View Threaded
 
 


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