----- 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.ga...@brainsware.org URL: http://brainsware.org/
