Slashdot Mirror

http://click.pocoo.org/

I use the Pelican static website generator for my static websites. I got Python to massage the data and Jinja2 for the template engine. I see no need to us OOP on the backend. If I did, Python can do OOP.

Unintended Affordances
(or why I believe encrypting everything is a bad idea) is worth a read on this.

I am not sure I agree on every point, but it's well thought out post.

this, and I am not sure how whomever decided the string/unicode changes in 3.x with no 2.x backwards compatibility couldn't figure out that it would be very unlikely that people would port all their code right away. This blog post I read a few days ago sums up some issues pretty well

http://lucumr.pocoo.org/2014/1/5/unicode-in-2-and-3/

Python, Python is my favorite language, however it isn't that good for web.

Go home, comment. You're drunk.

Django, Pylons, Bottle, Flask, TurboGears, Zope, Web2Py...

And that's just some of the popular frameworks..

CoffeeScript has a pretty serious flaw that the author is too stubborn (or perhaps too dumb) to recognize as being a flaw.

If the rumours are true, BitBucket was a blatant screen-for-screen imitation of GitHub's design:

I understand that imitation is flattering to some point and copying one or two things is cool, but BitBucket copied our website screen for screen in nearly every major aspect without asking for permission or acknowledging the theft.

If the owners of Bitbucket have no qualms about stealing GitHub's creation ... should you really trust them with yours?

I thought it was worth $7 per month to go with GitHub for this reason.

YMMV.

these too: http://paste.pocoo.org/raw/564896/ beersmith-2.0.60.ebuild (non-free, 21-day trial) http://paste.pocoo.org/raw/564897/ qbrew-0.4.1.ebuild

these too: http://paste.pocoo.org/raw/564896/ beersmith-2.0.60.ebuild (non-free, 21-day trial) http://paste.pocoo.org/raw/564897/ qbrew-0.4.1.ebuild

http://paste.pocoo.org/raw/564895/ brewtarget-1.2.4-r1.ebuild

The problem is not LaTeX, but TeX itself: it is fundamentally geared toward rendering text as glyphs at a specific size, then grouping those together to make lines, and arranging lines to paragraphs. That is all it ever does, and it is fantastic at doing it.

LaTeX is simply the *wrong* tool for the job of writing ebooks in epub and mobi, which need to have a dynamic document flow. LaTeX makes a very static, brittle document flow, because it was meant to. That was a feature, not a flaw.

What we need is a good workflow from one source format (like restructuredtext, markdown, etc.) into multiple good output formats (LaTeX/PDF, mobipocket / Kindle, epub, HTML). The closest I know of is Sphinx, but its epub output is in its infancy, and it has no support for the mobi / azw formats yet.

I've been using Django for a while now on my web app, having moved away from home-brewed PHP. Very easy to use, and encourages well-written and elegant code.

Another neat framework similar to Django is Flask.

Jinja2 is essentially a drop-in replacement for Django templates, and some consider Jinja2 to be superior.

I've been using Django for a while now on my web app, having moved away from home-brewed PHP. Very easy to use, and encourages well-written and elegant code.

Another neat framework similar to Django is Flask.

Jinja2 is essentially a drop-in replacement for Django templates, and some consider Jinja2 to be superior.

I'm sorry to see he didn't consider Flask. I've found it to be a beautiful microframework suited for any task one might use Web.py for.
If you are browsing for Python frameworks, you should give it a look.

Any python web framework shootout that features neither a flask nor a bottle is not worth drink...err reading!

If you start selecting tags to make the output look the way you want it to look, you don't understand XML (and subsequently shouldn't be using DocBook).

Anyone who was some experience writing documentation knows that the main objective is to write beautiful and readable documentation, not choosing the right markup...

It's not usually the author's job to do the beautification unless it's for self-publication through Lulu or for internal consumption. Conventional publishing houses have sets of standards governing how things must appear in their series, and the author does not get much chance to influence that except on special occasions.

Any author who is spending more time making it look pretty than actually writing readable, usable text needs firing. And they shouldn't have to spend time choosing the right markup (although, goddess help us, they do): they need editing software that provides them with the right choices, and right now it's the editors that suck, not the markup.

That's another problem with DocBook, it is a moving target with a standard that moves faster than the tools that support it.

This will always happen if you restrict yourself to pre-written tools.

I doubt most people who express that belief has actually tried to publish the same documentation in HTML and PDF form. DocBook produces PDF by first converting the document to LaTeX (so one is left wondering, why not use LaTeX itself in the first place?) and then use its tools to export to PDF.

Docbook itself does not produce anything: it's a markup format, not a program. You are confusing the markup format with one of the tools used to process it (OpenJade). There are dozens, if not hundreds, of others. Go look at them, or just write your own in XSLT. And I explained in an earlier comment why I transform my XML to LaTeX to produce PDF (another reason is that LaTeX produces very high quality PDF, which the other affordable XSL:FO tools don't).

...50%+ of a DocBook document is spent writing XML markup.

Then you are definitely either using the wrong editing tools, or the tools you are using are badly-written.

If you really want to know why DocBook sucks so much, you should check out Sphinx which is a document writing system done right. For some reason, it can manage without the overly verbose XML and idiotic semantic markup and still produce high quality documents that blow DocBook's out of the water.

Sphinx is very pretty, but it's going down a blind alley industrially unless it uses XML.

If you start selecting tags to make the output look the way you want it to look, you don't understand XML (and subsequently shouldn't be using DocBook).

Anyone who was some experience writing documentation knows that the main objective is to write beautiful and readable documentation, not choosing the right markup...

The fact that you couldn't find the tag but could find the other tags you've mentioned is just depressing, especially when those tags are most often sub-tags of a code tag block.

The CODE tag is new in DocBook 4.3. Version of jade shipped with Ubuntu 9.10 is 1.2.1 and it does not know about the CODE tag. That's another problem with DocBook, it is a moving target with a standard that moves faster than the tools that support it.

Just wait until you need to generate HTML help, Text file documentation, a web page manual, and a printed PDF of the same core documentation. The single-source design of DocBook will be much better appreciated then, if you learn how to use it.

I doubt most people who express that belief has actually tried to publish the same documentation in HTML and PDF form. DocBook produces PDF by first converting the document to LaTeX (so one is left wondering, why not use LaTeX itself in the first place?) and then use its tools to export to PDF. The result is a document as ugly and badly type-setted as an O'Reilly book. The HTML output basically looks like a raw data dump of the text, like this book for example. That's underwhelming to say the least, considering that 50%+ of a DocBook document is spent writing XML markup.

If you really want to know why DocBook sucks so much, you should check out Sphinx which is a document writing system done right. For some reason, it can manage without the overly verbose XML and idiotic semantic markup and still produce high quality documents that blow DocBook's out of the water.

How does reStructuredText stack up against DocBook? It's on my "look into later" list for technical documentation. My first impression of it was pretty good, especially combined with the Sphinx document generator.

• SASS
• LESS
• CleverCSS

There are just 3 good reasons for comments in code: (a) to refer to a published paper describing an (obscure) algorithm, eg '[fast graph traversal algorithm, M. M. Balakrishnarajan and P. Venuvanalingam ,Computers & Chemistry, Volume 19, Issue 2, June 1995, Pages 101-106] , (b) to indicate an arcane, obscure usage, which would be better eliminated, but sometimes cannot be eg in device drivers, when merely addressing a device register has side effects, (c) to very briefly document major parts of program flow-meaning, if this isn't otherwise obvious.

A fourth reason: if you use something like Sphinx to autogenerate documentation from your code, then you should probably include at least a one-liner saying what each function or method does, and maybe you want to describe the parameters and the return values. (If you're using a language like Python, then of course you don't have the types of the parameters or the return values in the function definition, so you should document them.)

The problem with StackOverflow is that people will ask a question there rather than more appropriate forums. So rather than asking on the forum dedicated to Open Source package XYZ where there are going to be other people with very detailed knowledge about the topic, they ask on StackOverflow where you get people who quite often know little to nothing about the topic answering. Consequence is you get half assed responses which are often wrong, ill informed or don't give the full picture. This can be frustrating from the point of view of the authors of said package XYZ, because to stop the proliferation of the bogus information, they need to start monitoring StackOverflow as well as their own on topic forums and either answer the questions or waste time correcting the provided answers. End result is authors end up wasting more time than if people just asked on the correct forum to begin with.

That said, StackOverflow is at least a better forum than IRC, which is where many would otherwise end up. IRC can be even more of a PITA as people expect to be able to get solutions to complex issues based on a single line question, and with subsequent response in a matter of lines as well.

FWIW, there are some Open Source versions of StackOverflow being developed which you could install on your own systems, rather than having to pay someone else for a managed service. For example, see:

http://lucumr.pocoo.org/2009/9/2/plurk-solace-released
http://opensource.plurk.com/Solace/

(Mind you, there online documentation could be better - PHP's site for example, is so much friendlier).

They're actually hard at work on that problem too. In addition to Python 2.6 being released, the Python documentation is now generated using Sphinx. See for example the new tutorial output. Big WTF the first time I saw it, but it's a decent improvement with more in the pipeline.