You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@trafficserver.apache.org by Igor Galić <i....@brainsware.org> on 2011/05/20 01:18:44 UTC
Documentation: TODO
Hey folks,
Following my last email, here's a list of things that need attention,
before we can consider exposing our documentation to a larger
user-base. These are things you can do even if you couldn't put
together a coherent sentence at gunpoint.
If you would like to do any of the following points, please reply
to this mail, so people know you're making an effort.
The documentation can currently be found in
https://svn.apache.org/repos/asf/trafficserver/site/branches/ats-cms/
(in content) It's being auto deployed (svnpubsub) to
http://trafficserver.staging.apache.org/
Navigation (Perl)
=================
Right now we have Top|Next|Back style links which
don't seem to work in nested directories: (try the
"Next" link here, and then on the next document)
http://trafficserver.staging.apache.org/docs/trunk/admin/configuration-files/
I've started fiddling around with this
http://paste.ubuntu.com/610332/ + (slight mod to order.txt) to
generate something like this: http://paste.ubuntu.com/609268/ I'm not
sure this is feasible to put on every page, but it should at the very
least be put on the first page.
Anyway, a full [TOC] should be on every page.
CSS
===
Our customers should be able to clearly distinguish the single parts
of a document. So far this works pretty well with code blocks, and
that's about it :) It's very hard to tell at which depth level
(h1-h4) you are
Instead of tables as in the old docs, I have (ab)used definition
lists. The CSS could need some love...
As mentioned above, I'd like to fit a navigation on every HTML page,
while still being able to read it on my tiny laptop - If you think
that's a bad idea, say something!
Fonts
=====
I'm not very sure if the choice of fonts is the right one. I changed
body { font-family: sans-serif; } and it looks better. If you
disagree, say something
Search (HTML/JavaScript)
========================
Our old documentation has a Google search - our new documentation
should have that too! (Or, if you're bored and want to do
solr/lucene...) Our
Links to Doxygen (Perl)
=======================
Our Doxygen reference is currently created by buildbot and deployed
to http://ci.apache.org/projects/trafficserver/trunk/doxygen/ I would
like to have some custom Markdown "macro" which generates a link from
something like $FooBar::baz$ into a link to the appropriate function,
method, namespace, operator or whatever that's supposed to be amc
already has something like this. Bug him.
(My mails just keep getting longer ;)
i
--
Igor Galić
Tel: +43 (0) 664 886 22 883
Mail: i.galic@brainsware.org
URL: http://brainsware.org/
Re: Documentation: TODO
Posted by Jason Giedymin <ja...@gmail.com>.
You have privs to install plone on the apache domain and add it to the supported tool set?
-Jason
On Jun 7, 2011, at 5:22 PM, "w.p.w" <he...@gmail.com> wrote:
> I dont suck at css, I also rock Plone 4, I can use webdeveloper
> toolbar on firefox to fix things and pas it on.
> Also I am happy to host a site using Plone 4.1 for ATS.
>
> Peace
>
> Wyn
>
> 2011/6/8 Igor Galić <i....@brainsware.org>:
>>
>>
>> ----- Original Message -----
>>> On 06/07/2011 02:54 PM, Miles Libbey wrote:
>>>>
>>>> Wow. Sounds like a project to tackle when I get a lot smarter. I
>>>> hope this both sounds a lot less daunting for others, and
>>>> something like this is rarely needed.
>>>>
>>>> I'll download the html and make some modifications to the pages.
>>>
>>> I agree, hopefully the tools will improve so mere mortals like me can
>>> also help with docs.
>>
>> I am a mere mortal. I think I am.
>>
>>>> IMO, the current staged front page does not look good. The
>>>> projects that have front pages that I think look decent (Cassandra
>>>> (http://cassandra.apache.org/), Memcached (http://memcached.org/),
>>>> Wordpress (http://wordpress.org/), Redhat
>>>> (http://www.redhat.com/), Miro (http://www.getmiro.com/), Pidgim
>>>> (http://www.pidgin.im/), etc) have mixed grids, with 1-3 columns
>>>> per 'row.' I'm ok with not using the current live front page
>>>> design -- but, it really should be somewhat purposely designed --
>>>> the current staged front page gives me a feeling it got the
>>>> default documentation treatment, and suffers as a result. A bit of
>>>> css isn't really going to help that -- there isn't enough document
>>>> structure to change much.
>>>
>>> +1. I actually like the look and feel of our current home page a lot.
>>> I
>>> was hoping that we could keep it, or at least something similar. I
>>> think
>>> part of the problem is that no one (other than you Miles) is really
>>> comfortable with site designs, CSS etc. So, it'd be great to get your
>>> help here I think.
>>
>> The current staging page is a result of me migrating the content to
>> and neglecting the style -- simply because I suck at CSS.
>>
>>> -- leif
>>>
>>>
>>
>> --
>> Igor Galić
>>
>> Tel: +43 (0) 664 886 22 883
>> Mail: i.galic@brainsware.org
>> URL: http://brainsware.org/
>>
Re: Documentation: TODO
Posted by "w.p.w" <he...@gmail.com>.
I dont suck at css, I also rock Plone 4, I can use webdeveloper
toolbar on firefox to fix things and pas it on.
Also I am happy to host a site using Plone 4.1 for ATS.
Peace
Wyn
2011/6/8 Igor Galić <i....@brainsware.org>:
>
>
> ----- Original Message -----
>> On 06/07/2011 02:54 PM, Miles Libbey wrote:
>> >
>> > Wow. Sounds like a project to tackle when I get a lot smarter. I
>> > hope this both sounds a lot less daunting for others, and
>> > something like this is rarely needed.
>> >
>> > I'll download the html and make some modifications to the pages.
>>
>> I agree, hopefully the tools will improve so mere mortals like me can
>> also help with docs.
>
> I am a mere mortal. I think I am.
>
>> > IMO, the current staged front page does not look good. The
>> > projects that have front pages that I think look decent (Cassandra
>> > (http://cassandra.apache.org/), Memcached (http://memcached.org/),
>> > Wordpress (http://wordpress.org/), Redhat
>> > (http://www.redhat.com/), Miro (http://www.getmiro.com/), Pidgim
>> > (http://www.pidgin.im/), etc) have mixed grids, with 1-3 columns
>> > per 'row.' I'm ok with not using the current live front page
>> > design -- but, it really should be somewhat purposely designed --
>> > the current staged front page gives me a feeling it got the
>> > default documentation treatment, and suffers as a result. A bit of
>> > css isn't really going to help that -- there isn't enough document
>> > structure to change much.
>>
>> +1. I actually like the look and feel of our current home page a lot.
>> I
>> was hoping that we could keep it, or at least something similar. I
>> think
>> part of the problem is that no one (other than you Miles) is really
>> comfortable with site designs, CSS etc. So, it'd be great to get your
>> help here I think.
>
> The current staging page is a result of me migrating the content to
> and neglecting the style -- simply because I suck at CSS.
>
>> -- leif
>>
>>
>
> --
> Igor Galić
>
> Tel: +43 (0) 664 886 22 883
> Mail: i.galic@brainsware.org
> URL: http://brainsware.org/
>
Re: Documentation: TODO
Posted by "w.p.w" <he...@gmail.com>.
Hello
Yes, my bad :) we can handle putting in themes and help with the UI
along with the devs and everyone else who wants to contribute.
Shoulkd there be a tieline / roadmap for this ?
Peace
Wyn
On Wed, Jun 8, 2011 at 1:30 AM, Leif Hedstrom <zw...@apache.org> wrote:
> On 06/07/2011 04:20 PM, w.p.w wrote:
>>
>> Cool as, To install Plone 4 we would need access or a separate server,
>> this seems worth looking into with the project but unlikely to happen.
>
> Yeah, I think that's unlikely to happen. Best bet would be to contribute to
> the Apache CMS project, adding better tools, easier to use interfaces etc.
> etc.
>
>> Either way we can sort out the css, i would suggest that devs sketch
>> out a UI and theme and we can then make it happen.
>
> Everyone interested should participate, not necessarily just devs (and in
> fact, I think devs are bad with UI's typically, maybe with the exception of
> amc here). So, everyone should definitely feel welcome to come help in this
> effort.
>
> Cheers,
>
> -- Leif
>
>
Re: Documentation: TODO
Posted by Leif Hedstrom <zw...@apache.org>.
On 06/07/2011 04:20 PM, w.p.w wrote:
> Cool as, To install Plone 4 we would need access or a separate server,
> this seems worth looking into with the project but unlikely to happen.
Yeah, I think that's unlikely to happen. Best bet would be to contribute
to the Apache CMS project, adding better tools, easier to use interfaces
etc. etc.
> Either way we can sort out the css, i would suggest that devs sketch
> out a UI and theme and we can then make it happen.
Everyone interested should participate, not necessarily just devs (and
in fact, I think devs are bad with UI's typically, maybe with the
exception of amc here). So, everyone should definitely feel welcome to
come help in this effort.
Cheers,
-- Leif
Re: Documentation: TODO
Posted by "w.p.w" <he...@gmail.com>.
Cool as, To install Plone 4 we would need access or a separate server,
this seems worth looking into with the project but unlikely to happen.
Either way we can sort out the css, i would suggest that devs sketch
out a UI and theme and we can then make it happen.
Peace
Wyn
On Wed, Jun 8, 2011 at 1:17 AM, Leif Hedstrom <zw...@apache.org> wrote:
> On 06/07/2011 04:10 PM, w.p.w wrote:
>>
>> I do not have Privileges there but I am a part owner of devaus.com and
>> we handle sites like nokia and RTV world wide, given privileges I can
>> set it up anywhere of course but we can also host it.
>
> All www pages / docs have to be hosted on apache.org servers.
>
> -- Leif
>
>
Re: Documentation: TODO
Posted by Leif Hedstrom <zw...@apache.org>.
On 06/07/2011 04:10 PM, w.p.w wrote:
> I do not have Privileges there but I am a part owner of devaus.com and
> we handle sites like nokia and RTV world wide, given privileges I can
> set it up anywhere of course but we can also host it.
All www pages / docs have to be hosted on apache.org servers.
-- Leif
Re: Documentation: TODO
Posted by "w.p.w" <he...@gmail.com>.
I do not have Privileges there but I am a part owner of devaus.com and
we handle sites like nokia and RTV world wide, given privileges I can
set it up anywhere of course but we can also host it.
Peace
Wyn
On Wed, Jun 8, 2011 at 1:00 AM, Miles Libbey <mi...@yahoo-inc.com> wrote:
>
> On Jun 7, 2011, at 2:15 PM, Igor Galić wrote:
>
>>>> IMO, the current staged front page does not look good. The
>>>> projects that have front pages that I think look decent (Cassandra
>>>> (http://cassandra.apache.org/), Memcached (http://memcached.org/),
>>>> Wordpress (http://wordpress.org/), Redhat
>>>> (http://www.redhat.com/), Miro (http://www.getmiro.com/), Pidgim
>>>> (http://www.pidgin.im/), etc) have mixed grids, with 1-3 columns
>>>> per 'row.' I'm ok with not using the current live front page
>>>> design -- but, it really should be somewhat purposely designed --
>>>> the current staged front page gives me a feeling it got the
>>>> default documentation treatment, and suffers as a result. A bit of
>>>> css isn't really going to help that -- there isn't enough document
>>>> structure to change much.
>>>
>>> +1. I actually like the look and feel of our current home page a lot.
>>> I
>>> was hoping that we could keep it, or at least something similar. I
>>> think
>>> part of the problem is that no one (other than you Miles) is really
>>> comfortable with site designs, CSS etc. So, it'd be great to get your
>>> help here I think.
>>
>> The current staging page is a result of me migrating the content to
>> and neglecting the style -- simply because I suck at CSS.
>
>
> Happy to help -- but, honestly, I've no idea where to even start on this one. I started looking at it with an intent to make a few css changes to replicate the current live home page, but, realized:
> - the front page likely needs some additional CSS that would be irrelevant to (and/or conflicting with) the rest of the site ... and no clue how to add that.
> - even if I could add them, the html doesn't have the page structural elements to target the elements -- and no clue how to give the sections the appropriate targets.
>
> For the current page, my CSS skillz are way overrated. I went to a point and click site layout generator:
> http://developer.yahoo.com/yui/grids/builder/
> clicked a few buttons, and copied the resulting output. The linked in styles have all the smarts of getting columns and defining widths cross-browser.
>
> miles
Re: Documentation: TODO
Posted by Igor Galić <i....@brainsware.org>.
----- Original Message -----
>
> On Jun 7, 2011, at 2:15 PM, Igor Galić wrote:
>
> >>> IMO, the current staged front page does not look good. The
> >>> projects that have front pages that I think look decent
> >>> (Cassandra
> >>> (http://cassandra.apache.org/), Memcached
> >>> (http://memcached.org/),
> >>> Wordpress (http://wordpress.org/), Redhat
> >>> (http://www.redhat.com/), Miro (http://www.getmiro.com/), Pidgim
> >>> (http://www.pidgin.im/), etc) have mixed grids, with 1-3 columns
> >>> per 'row.' I'm ok with not using the current live front page
> >>> design -- but, it really should be somewhat purposely designed --
> >>> the current staged front page gives me a feeling it got the
> >>> default documentation treatment, and suffers as a result. A bit
> >>> of
> >>> css isn't really going to help that -- there isn't enough
> >>> document
> >>> structure to change much.
> >>
> >> +1. I actually like the look and feel of our current home page a
> >> lot.
> >> I
> >> was hoping that we could keep it, or at least something similar. I
> >> think
> >> part of the problem is that no one (other than you Miles) is
> >> really
> >> comfortable with site designs, CSS etc. So, it'd be great to get
> >> your
> >> help here I think.
> >
> > The current staging page is a result of me migrating the content to
> > and neglecting the style -- simply because I suck at CSS.
>
>
> Happy to help -- but, honestly, I've no idea where to even start on
> this one. I started looking at it with an intent to make a few css
> changes to replicate the current live home page, but, realized:
> - the front page likely needs some additional CSS that would be
> irrelevant to (and/or conflicting with) the rest of the site ... and
> no clue how to add that.
> - even if I could add them, the html doesn't have the page structural
> elements to target the elements -- and no clue how to give the
> sections the appropriate targets.
r1135344 - I created a distinction between front page and docs page
That way we can style the whole thing in parts.
I really hope that helps a bit and lowers the bar.
If there's anything else in regard to the CMS I can help with,
please point it out.
> For the current page, my CSS skillz are way overrated. I went to a
> point and click site layout generator:
> http://developer.yahoo.com/yui/grids/builder/
> clicked a few buttons, and copied the resulting output. The linked
> in styles have all the smarts of getting columns and defining widths
> cross-browser.
>
> miles
i
--
Igor Galić
Tel: +43 (0) 664 886 22 883
Mail: i.galic@brainsware.org
URL: http://brainsware.org/
Re: Documentation: TODO
Posted by Miles Libbey <mi...@yahoo-inc.com>.
On Jun 7, 2011, at 2:15 PM, Igor Galić wrote:
>>> IMO, the current staged front page does not look good. The
>>> projects that have front pages that I think look decent (Cassandra
>>> (http://cassandra.apache.org/), Memcached (http://memcached.org/),
>>> Wordpress (http://wordpress.org/), Redhat
>>> (http://www.redhat.com/), Miro (http://www.getmiro.com/), Pidgim
>>> (http://www.pidgin.im/), etc) have mixed grids, with 1-3 columns
>>> per 'row.' I'm ok with not using the current live front page
>>> design -- but, it really should be somewhat purposely designed --
>>> the current staged front page gives me a feeling it got the
>>> default documentation treatment, and suffers as a result. A bit of
>>> css isn't really going to help that -- there isn't enough document
>>> structure to change much.
>>
>> +1. I actually like the look and feel of our current home page a lot.
>> I
>> was hoping that we could keep it, or at least something similar. I
>> think
>> part of the problem is that no one (other than you Miles) is really
>> comfortable with site designs, CSS etc. So, it'd be great to get your
>> help here I think.
>
> The current staging page is a result of me migrating the content to
> and neglecting the style -- simply because I suck at CSS.
Happy to help -- but, honestly, I've no idea where to even start on this one. I started looking at it with an intent to make a few css changes to replicate the current live home page, but, realized:
- the front page likely needs some additional CSS that would be irrelevant to (and/or conflicting with) the rest of the site ... and no clue how to add that.
- even if I could add them, the html doesn't have the page structural elements to target the elements -- and no clue how to give the sections the appropriate targets.
For the current page, my CSS skillz are way overrated. I went to a point and click site layout generator:
http://developer.yahoo.com/yui/grids/builder/
clicked a few buttons, and copied the resulting output. The linked in styles have all the smarts of getting columns and defining widths cross-browser.
miles
Re: Documentation: TODO
Posted by Igor Galić <i....@brainsware.org>.
----- Original Message -----
> On 06/07/2011 02:54 PM, Miles Libbey wrote:
> >
> > Wow. Sounds like a project to tackle when I get a lot smarter. I
> > hope this both sounds a lot less daunting for others, and
> > something like this is rarely needed.
> >
> > I'll download the html and make some modifications to the pages.
>
> I agree, hopefully the tools will improve so mere mortals like me can
> also help with docs.
I am a mere mortal. I think I am.
> > IMO, the current staged front page does not look good. The
> > projects that have front pages that I think look decent (Cassandra
> > (http://cassandra.apache.org/), Memcached (http://memcached.org/),
> > Wordpress (http://wordpress.org/), Redhat
> > (http://www.redhat.com/), Miro (http://www.getmiro.com/), Pidgim
> > (http://www.pidgin.im/), etc) have mixed grids, with 1-3 columns
> > per 'row.' I'm ok with not using the current live front page
> > design -- but, it really should be somewhat purposely designed --
> > the current staged front page gives me a feeling it got the
> > default documentation treatment, and suffers as a result. A bit of
> > css isn't really going to help that -- there isn't enough document
> > structure to change much.
>
> +1. I actually like the look and feel of our current home page a lot.
> I
> was hoping that we could keep it, or at least something similar. I
> think
> part of the problem is that no one (other than you Miles) is really
> comfortable with site designs, CSS etc. So, it'd be great to get your
> help here I think.
The current staging page is a result of me migrating the content to
and neglecting the style -- simply because I suck at CSS.
> -- leif
>
>
--
Igor Galić
Tel: +43 (0) 664 886 22 883
Mail: i.galic@brainsware.org
URL: http://brainsware.org/
Re: Documentation: TODO
Posted by Leif Hedstrom <zw...@apache.org>.
On 06/07/2011 02:54 PM, Miles Libbey wrote:
>
> Wow. Sounds like a project to tackle when I get a lot smarter. I hope this both sounds a lot less daunting for others, and something like this is rarely needed.
>
> I'll download the html and make some modifications to the pages.
I agree, hopefully the tools will improve so mere mortals like me can
also help with docs.
>
> IMO, the current staged front page does not look good. The projects that have front pages that I think look decent (Cassandra (http://cassandra.apache.org/), Memcached (http://memcached.org/), Wordpress (http://wordpress.org/), Redhat (http://www.redhat.com/), Miro (http://www.getmiro.com/), Pidgim (http://www.pidgin.im/), etc) have mixed grids, with 1-3 columns per 'row.' I'm ok with not using the current live front page design -- but, it really should be somewhat purposely designed -- the current staged front page gives me a feeling it got the default documentation treatment, and suffers as a result. A bit of css isn't really going to help that -- there isn't enough document structure to change much.
+1. I actually like the look and feel of our current home page a lot. I
was hoping that we could keep it, or at least something similar. I think
part of the problem is that no one (other than you Miles) is really
comfortable with site designs, CSS etc. So, it'd be great to get your
help here I think.
-- leif
Re: Documentation: TODO
Posted by Miles Libbey <mi...@yahoo-inc.com>.
On Jun 7, 2011, at 8:20 AM, Igor Galić wrote:
> You *could* use the web interface:
>
> https://cms.apache.org/ -- but right now, that has the old HTML site in there.
> We should probably change that.
>
> I pre-build the changes on my local box.
> To do this I check out the cms:
>
> svn co https://svn.apache.org/repos/infra/websites/cms/build cms
>
> You'll need the python-markdown version of markdown installed.
> Given that in Ubuntu it's called /usr/bin/markdown_py - I *symlink* it to /usr/local/bin
> Where, by default, it's expected to be anyway.
>
> There are a number of CPAN modules that you'll need:
> SVN::Client, SVN::Wc
> LWP::Simple
> XML::Atom
> XML::RSS::Parser::Lite
>
> Then, to build:
>
> i.galic@panic ~/Projects/asf/cms (svn)-[build:787652] % export MARKDOWN_SOCKET=$PWD/logs/mardownd.pipe
> i.galic@panic ~/Projects/asf/cms (svn)-[build:787652] % python markdownd.py
> i.galic@panic ~/Projects/asf/cms (svn)-[build:787652] % ..
> i.galic@panic ~/Projects/asf % $PWD/cms/build_site.pl --source-base ats-cms --target-base ats-cms-docroot
> Can't open cgi-bin [skipping]: No such file or directory at /home/i.galic/Projects/asf/cms/build_site.pl line 57.
> i.galic@panic ~/Projects/asf
Wow. Sounds like a project to tackle when I get a lot smarter. I hope this both sounds a lot less daunting for others, and something like this is rarely needed.
I'll download the html and make some modifications to the pages.
>> Do the site pages (home and download) have to have the same CSS as
>> the documentation?
>
> Probably not - I'm pretty sure there's a simple and sane way to give
> them a different CSS. But I would suggest to really stick to one
> design.. It's kinda confusing - or irritating when it switches.
>
> Witness: http://httpd.apache.org/ vs
> http://httpd.apache.org/docs/trunk/mod/core.html#adddefaultcharset
The general look and feed doesn't have to change.
IMO, the current staged front page does not look good. The projects that have front pages that I think look decent (Cassandra (http://cassandra.apache.org/), Memcached (http://memcached.org/), Wordpress (http://wordpress.org/), Redhat (http://www.redhat.com/), Miro (http://www.getmiro.com/), Pidgim (http://www.pidgin.im/), etc) have mixed grids, with 1-3 columns per 'row.' I'm ok with not using the current live front page design -- but, it really should be somewhat purposely designed -- the current staged front page gives me a feeling it got the default documentation treatment, and suffers as a result. A bit of css isn't really going to help that -- there isn't enough document structure to change much.
>>> Fonts
>>> =====
>>>
>
> Again, I'm suggesting to stick to one font(style). I don't know
> if my choice was any good.
Actually, you've done the opposite. You are letting each browser/OS choose for you instead of sticking to one. To get something more consistent, you should borrow from the css resets -- like
font:13px/1.231 arial,helvetica,clean,sans-serif;
*font-size:small;
*font:x-small;
>
>>>
>>> Search (HTML/JavaScript)
>>> ========================
>>>
>>> Our old documentation has a Google search - our new documentation
>>> should have that too! (Or, if you're bored and want to do
>>> solr/lucene...) Our
>>
>> What is the primary issue -- ie, is there a reason we can't just copy
>> over the form and search page?
>
> There probably isn't. The reason why I didn't include it was because it
> contained icky stuff I don't know how to handle (JavaScript and Google)
Ah. I used Google because it was 16 lines of cut and paste html/javascript and configuring it to search confluence, the mail-archives and the site took typing in 3 addresses. I don't think we should go live with the new stuff until we have search -- it looks to be our 5th most popular page.
miles
Re: Documentation: TODO
Posted by Igor Galić <i....@brainsware.org>.
----- Original Message -----
> On May 19, 2011, at 4:18 PM, Igor Galić wrote:
> > Hey folks,
> >
> > Following my last email, here's a list of things that need
> > attention,
> > before we can consider exposing our documentation to a larger
> > user-base. These are things you can do even if you couldn't put
> > together a coherent sentence at gunpoint.
> > ...
> > CSS
> > ===
> >
> > Our customers should be able to clearly distinguish the single
> > parts
> > of a document. So far this works pretty well with code blocks, and
> > that's about it :) It's very hard to tell at which depth level
> > (h1-h4) you are
> >
> > Instead of tables as in the old docs, I have (ab)used definition
> > lists. The CSS could need some love...
> >
> > As mentioned above, I'd like to fit a navigation on every HTML
> > page,
> > while still being able to read it on my tiny laptop - If you think
> > that's a bad idea, say something!
>
> is the only way to try out tweaks to commit changes to
> https://svn.apache.org/repos/asf/trafficserver/site/branches/ats-cms/content/styles/
> ? (that is, in the HTML style, I could load the document in a
> browser, make tweaks to the CSS, and refresh the page to see how it
> looks. How does the new process work?
You *could* use the web interface:
https://cms.apache.org/ -- but right now, that has the old HTML site in there.
We should probably change that.
I pre-build the changes on my local box.
To do this I check out the cms:
svn co https://svn.apache.org/repos/infra/websites/cms/build cms
You'll need the python-markdown version of markdown installed.
Given that in Ubuntu it's called /usr/bin/markdown_py - I *symlink* it to /usr/local/bin
Where, by default, it's expected to be anyway.
There are a number of CPAN modules that you'll need:
SVN::Client, SVN::Wc
LWP::Simple
XML::Atom
XML::RSS::Parser::Lite
Then, to build:
i.galic@panic ~/Projects/asf/cms (svn)-[build:787652] % export MARKDOWN_SOCKET=$PWD/logs/mardownd.pipe
i.galic@panic ~/Projects/asf/cms (svn)-[build:787652] % python markdownd.py
i.galic@panic ~/Projects/asf/cms (svn)-[build:787652] % ..
i.galic@panic ~/Projects/asf % $PWD/cms/build_site.pl --source-base ats-cms --target-base ats-cms-docroot
Can't open cgi-bin [skipping]: No such file or directory at /home/i.galic/Projects/asf/cms/build_site.pl line 57.
i.galic@panic ~/Projects/asf %
> Do the site pages (home and download) have to have the same CSS as
> the documentation?
Probably not - I'm pretty sure there's a simple and sane way to give
them a different CSS. But I would suggest to really stick to one
design.. It's kinda confusing - or irritating when it switches.
Witness: http://httpd.apache.org/ vs
http://httpd.apache.org/docs/trunk/mod/core.html#adddefaultcharset
> > Fonts
> > =====
> >
> > I'm not very sure if the choice of fonts is the right one. I
> > changed
> > body { font-family: sans-serif; } and it looks better. If you
> > disagree, say something
>
> heh. The current home page font starts with the default sans-serif
> font, arial. falling back to another sans-serif font (Helvetica)
> and then finally falls back to the sans-serif family. In the
> documentation side, the font is set to the default sans-serif font,
> arial -- there should not be a major difference in that change :)
Again, I'm suggesting to stick to one font(style). I don't know
if my choice was any good.
> >
> > Search (HTML/JavaScript)
> > ========================
> >
> > Our old documentation has a Google search - our new documentation
> > should have that too! (Or, if you're bored and want to do
> > solr/lucene...) Our
>
> What is the primary issue -- ie, is there a reason we can't just copy
> over the form and search page?
There probably isn't. The reason why I didn't include it was because it
contained icky stuff I don't know how to handle (JavaScript and Google)
> miles
i
--
Igor Galić
Tel: +43 (0) 664 886 22 883
Mail: i.galic@brainsware.org
URL: http://brainsware.org/
Re: Documentation: TODO
Posted by Miles Libbey <mi...@yahoo-inc.com>.
On May 19, 2011, at 4:18 PM, Igor Galić wrote:
> Hey folks,
>
> Following my last email, here's a list of things that need attention,
> before we can consider exposing our documentation to a larger
> user-base. These are things you can do even if you couldn't put
> together a coherent sentence at gunpoint.
> ...
> CSS
> ===
>
> Our customers should be able to clearly distinguish the single parts
> of a document. So far this works pretty well with code blocks, and
> that's about it :) It's very hard to tell at which depth level
> (h1-h4) you are
>
> Instead of tables as in the old docs, I have (ab)used definition
> lists. The CSS could need some love...
>
> As mentioned above, I'd like to fit a navigation on every HTML page,
> while still being able to read it on my tiny laptop - If you think
> that's a bad idea, say something!
is the only way to try out tweaks to commit changes to
https://svn.apache.org/repos/asf/trafficserver/site/branches/ats-cms/content/styles/ ? (that is, in the HTML style, I could load the document in a browser, make tweaks to the CSS, and refresh the page to see how it looks. How does the new process work?
Do the site pages (home and download) have to have the same CSS as the documentation?
> Fonts
> =====
>
> I'm not very sure if the choice of fonts is the right one. I changed
> body { font-family: sans-serif; } and it looks better. If you
> disagree, say something
heh. The current home page font starts with the default sans-serif font, arial. falling back to another sans-serif font (Helvetica) and then finally falls back to the sans-serif family. In the documentation side, the font is set to the default sans-serif font, arial -- there should not be a major difference in that change :)
>
> Search (HTML/JavaScript)
> ========================
>
> Our old documentation has a Google search - our new documentation
> should have that too! (Or, if you're bored and want to do
> solr/lucene...) Our
What is the primary issue -- ie, is there a reason we can't just copy over the form and search page?
miles
Re: Documentation: TODO
Posted by Igor Galić <i....@brainsware.org>.
----- Original Message -----
> Hi Igor,
Hi Manish,
> Let me know how I can help.
Like I said, if you know CSS, JS or Perl, you can help
with any of the issues below.
> Thanks,
> Manish
>
>
> On 5/19/11, Igor Galić <i....@brainsware.org> wrote:
> >
> > Hey folks,
> >
> > Following my last email, here's a list of things that need
> > attention,
> > before we can consider exposing our documentation to a larger
> > user-base. These are things you can do even if you couldn't put
> > together a coherent sentence at gunpoint.
> >
> >
> > If you would like to do any of the following points, please reply
> > to this mail, so people know you're making an effort.
> >
> > The documentation can currently be found in
> > https://svn.apache.org/repos/asf/trafficserver/site/branches/ats-cms/
> > (in content) It's being auto deployed (svnpubsub) to
> > http://trafficserver.staging.apache.org/
> >
> > Navigation (Perl)
> > =================
> >
> > Right now we have Top|Next|Back style links which
> > don't seem to work in nested directories: (try the
> > "Next" link here, and then on the next document)
> > http://trafficserver.staging.apache.org/docs/trunk/admin/configuration-files/
> >
> > I've started fiddling around with this
> > http://paste.ubuntu.com/610332/ + (slight mod to order.txt) to
> > generate something like this: http://paste.ubuntu.com/609268/ I'm
> > not
> > sure this is feasible to put on every page, but it should at the
> > very
> > least be put on the first page.
> >
> > Anyway, a full [TOC] should be on every page.
> >
> > CSS
> > ===
> >
> > Our customers should be able to clearly distinguish the single
> > parts
> > of a document. So far this works pretty well with code blocks, and
> > that's about it :) It's very hard to tell at which depth level
> > (h1-h4) you are
> >
> > Instead of tables as in the old docs, I have (ab)used definition
> > lists. The CSS could need some love...
> >
> > As mentioned above, I'd like to fit a navigation on every HTML
> > page,
> > while still being able to read it on my tiny laptop - If you think
> > that's a bad idea, say something!
> >
> > Fonts
> > =====
> >
> > I'm not very sure if the choice of fonts is the right one. I
> > changed
> > body { font-family: sans-serif; } and it looks better. If you
> > disagree, say something
> >
> > Search (HTML/JavaScript)
> > ========================
> >
> > Our old documentation has a Google search - our new documentation
> > should have that too! (Or, if you're bored and want to do
> > solr/lucene...) Our
> >
> > Links to Doxygen (Perl)
> > =======================
> >
> > Our Doxygen reference is currently created by buildbot and deployed
> > to http://ci.apache.org/projects/trafficserver/trunk/doxygen/ I
> > would
> > like to have some custom Markdown "macro" which generates a link
> > from
> > something like $FooBar::baz$ into a link to the appropriate
> > function,
> > method, namespace, operator or whatever that's supposed to be amc
> > already has something like this. Bug him.
> >
> >
> >
> > (My mails just keep getting longer ;)
> >
> > i
> >
> > --
> > Igor Galić
> >
> > Tel: +43 (0) 664 886 22 883
> > Mail: i.galic@brainsware.org
> > URL: http://brainsware.org/
> >
>
> --
> Sent from my mobile device
i
--
Igor Galić
Tel: +43 (0) 664 886 22 883
Mail: i.galic@brainsware.org
URL: http://brainsware.org/
Re: Documentation: TODO
Posted by Igor Galić <i....@brainsware.org>.
----- Original Message -----
> Hi Igor,
Hi Manish,
> Let me know how I can help.
Like I said, if you know CSS, JS or Perl, you can help
with any of the issues below.
> Thanks,
> Manish
>
>
> On 5/19/11, Igor Galić <i....@brainsware.org> wrote:
> >
> > Hey folks,
> >
> > Following my last email, here's a list of things that need
> > attention,
> > before we can consider exposing our documentation to a larger
> > user-base. These are things you can do even if you couldn't put
> > together a coherent sentence at gunpoint.
> >
> >
> > If you would like to do any of the following points, please reply
> > to this mail, so people know you're making an effort.
> >
> > The documentation can currently be found in
> > https://svn.apache.org/repos/asf/trafficserver/site/branches/ats-cms/
> > (in content) It's being auto deployed (svnpubsub) to
> > http://trafficserver.staging.apache.org/
> >
> > Navigation (Perl)
> > =================
> >
> > Right now we have Top|Next|Back style links which
> > don't seem to work in nested directories: (try the
> > "Next" link here, and then on the next document)
> > http://trafficserver.staging.apache.org/docs/trunk/admin/configuration-files/
> >
> > I've started fiddling around with this
> > http://paste.ubuntu.com/610332/ + (slight mod to order.txt) to
> > generate something like this: http://paste.ubuntu.com/609268/ I'm
> > not
> > sure this is feasible to put on every page, but it should at the
> > very
> > least be put on the first page.
> >
> > Anyway, a full [TOC] should be on every page.
> >
> > CSS
> > ===
> >
> > Our customers should be able to clearly distinguish the single
> > parts
> > of a document. So far this works pretty well with code blocks, and
> > that's about it :) It's very hard to tell at which depth level
> > (h1-h4) you are
> >
> > Instead of tables as in the old docs, I have (ab)used definition
> > lists. The CSS could need some love...
> >
> > As mentioned above, I'd like to fit a navigation on every HTML
> > page,
> > while still being able to read it on my tiny laptop - If you think
> > that's a bad idea, say something!
> >
> > Fonts
> > =====
> >
> > I'm not very sure if the choice of fonts is the right one. I
> > changed
> > body { font-family: sans-serif; } and it looks better. If you
> > disagree, say something
> >
> > Search (HTML/JavaScript)
> > ========================
> >
> > Our old documentation has a Google search - our new documentation
> > should have that too! (Or, if you're bored and want to do
> > solr/lucene...) Our
> >
> > Links to Doxygen (Perl)
> > =======================
> >
> > Our Doxygen reference is currently created by buildbot and deployed
> > to http://ci.apache.org/projects/trafficserver/trunk/doxygen/ I
> > would
> > like to have some custom Markdown "macro" which generates a link
> > from
> > something like $FooBar::baz$ into a link to the appropriate
> > function,
> > method, namespace, operator or whatever that's supposed to be amc
> > already has something like this. Bug him.
> >
> >
> >
> > (My mails just keep getting longer ;)
> >
> > i
> >
> > --
> > Igor Galić
> >
> > Tel: +43 (0) 664 886 22 883
> > Mail: i.galic@brainsware.org
> > URL: http://brainsware.org/
> >
>
> --
> Sent from my mobile device
i
--
Igor Galić
Tel: +43 (0) 664 886 22 883
Mail: i.galic@brainsware.org
URL: http://brainsware.org/
Re: Documentation: TODO
Posted by Manish Pandey <ma...@gmail.com>.
Hi Igor,
Let me know how I can help.
Thanks,
Manish
On 5/19/11, Igor Galić <i....@brainsware.org> wrote:
>
> Hey folks,
>
> Following my last email, here's a list of things that need attention,
> before we can consider exposing our documentation to a larger
> user-base. These are things you can do even if you couldn't put
> together a coherent sentence at gunpoint.
>
>
> If you would like to do any of the following points, please reply
> to this mail, so people know you're making an effort.
>
> The documentation can currently be found in
> https://svn.apache.org/repos/asf/trafficserver/site/branches/ats-cms/
> (in content) It's being auto deployed (svnpubsub) to
> http://trafficserver.staging.apache.org/
>
> Navigation (Perl)
> =================
>
> Right now we have Top|Next|Back style links which
> don't seem to work in nested directories: (try the
> "Next" link here, and then on the next document)
> http://trafficserver.staging.apache.org/docs/trunk/admin/configuration-files/
>
> I've started fiddling around with this
> http://paste.ubuntu.com/610332/ + (slight mod to order.txt) to
> generate something like this: http://paste.ubuntu.com/609268/ I'm not
> sure this is feasible to put on every page, but it should at the very
> least be put on the first page.
>
> Anyway, a full [TOC] should be on every page.
>
> CSS
> ===
>
> Our customers should be able to clearly distinguish the single parts
> of a document. So far this works pretty well with code blocks, and
> that's about it :) It's very hard to tell at which depth level
> (h1-h4) you are
>
> Instead of tables as in the old docs, I have (ab)used definition
> lists. The CSS could need some love...
>
> As mentioned above, I'd like to fit a navigation on every HTML page,
> while still being able to read it on my tiny laptop - If you think
> that's a bad idea, say something!
>
> Fonts
> =====
>
> I'm not very sure if the choice of fonts is the right one. I changed
> body { font-family: sans-serif; } and it looks better. If you
> disagree, say something
>
> Search (HTML/JavaScript)
> ========================
>
> Our old documentation has a Google search - our new documentation
> should have that too! (Or, if you're bored and want to do
> solr/lucene...) Our
>
> Links to Doxygen (Perl)
> =======================
>
> Our Doxygen reference is currently created by buildbot and deployed
> to http://ci.apache.org/projects/trafficserver/trunk/doxygen/ I would
> like to have some custom Markdown "macro" which generates a link from
> something like $FooBar::baz$ into a link to the appropriate function,
> method, namespace, operator or whatever that's supposed to be amc
> already has something like this. Bug him.
>
>
>
> (My mails just keep getting longer ;)
>
> i
>
> --
> Igor Galić
>
> Tel: +43 (0) 664 886 22 883
> Mail: i.galic@brainsware.org
> URL: http://brainsware.org/
>
--
Sent from my mobile device
Re: Documentation: TODO
Posted by Manish Pandey <ma...@gmail.com>.
Hi Igor,
Let me know how I can help.
Thanks,
Manish
On 5/19/11, Igor Galić <i....@brainsware.org> wrote:
>
> Hey folks,
>
> Following my last email, here's a list of things that need attention,
> before we can consider exposing our documentation to a larger
> user-base. These are things you can do even if you couldn't put
> together a coherent sentence at gunpoint.
>
>
> If you would like to do any of the following points, please reply
> to this mail, so people know you're making an effort.
>
> The documentation can currently be found in
> https://svn.apache.org/repos/asf/trafficserver/site/branches/ats-cms/
> (in content) It's being auto deployed (svnpubsub) to
> http://trafficserver.staging.apache.org/
>
> Navigation (Perl)
> =================
>
> Right now we have Top|Next|Back style links which
> don't seem to work in nested directories: (try the
> "Next" link here, and then on the next document)
> http://trafficserver.staging.apache.org/docs/trunk/admin/configuration-files/
>
> I've started fiddling around with this
> http://paste.ubuntu.com/610332/ + (slight mod to order.txt) to
> generate something like this: http://paste.ubuntu.com/609268/ I'm not
> sure this is feasible to put on every page, but it should at the very
> least be put on the first page.
>
> Anyway, a full [TOC] should be on every page.
>
> CSS
> ===
>
> Our customers should be able to clearly distinguish the single parts
> of a document. So far this works pretty well with code blocks, and
> that's about it :) It's very hard to tell at which depth level
> (h1-h4) you are
>
> Instead of tables as in the old docs, I have (ab)used definition
> lists. The CSS could need some love...
>
> As mentioned above, I'd like to fit a navigation on every HTML page,
> while still being able to read it on my tiny laptop - If you think
> that's a bad idea, say something!
>
> Fonts
> =====
>
> I'm not very sure if the choice of fonts is the right one. I changed
> body { font-family: sans-serif; } and it looks better. If you
> disagree, say something
>
> Search (HTML/JavaScript)
> ========================
>
> Our old documentation has a Google search - our new documentation
> should have that too! (Or, if you're bored and want to do
> solr/lucene...) Our
>
> Links to Doxygen (Perl)
> =======================
>
> Our Doxygen reference is currently created by buildbot and deployed
> to http://ci.apache.org/projects/trafficserver/trunk/doxygen/ I would
> like to have some custom Markdown "macro" which generates a link from
> something like $FooBar::baz$ into a link to the appropriate function,
> method, namespace, operator or whatever that's supposed to be amc
> already has something like this. Bug him.
>
>
>
> (My mails just keep getting longer ;)
>
> i
>
> --
> Igor Galić
>
> Tel: +43 (0) 664 886 22 883
> Mail: i.galic@brainsware.org
> URL: http://brainsware.org/
>
--
Sent from my mobile device