]ANN[ Vellum 0.16: Lots Of Documentation and Watching

[Zed A. Shaw]

Hi Everyone,

Just putting out an announcement that I've released a new version of
Vellum numbered 0.16. This version should be ready for people to use
as not much of the internal structure has changed in a great many
commits and it contains all the latest bug fixes.

It also has the beginning of an extensive PDF document describing how
to use it. This is still an in-progress work, so it has grammar
mistakes and spelling errors, but it does show off some nice
documentation wizardy I'm experimenting with in LaTeX.

Finally there's a new "watch" feature which is very handy described
further down. It simply watches a file and reruns your targets when
the file changes.


GETTING IT

Honestly, the easiest way is just:

sudo easy_install zapps vellum

If you want to build the book yourself and have all of TeX Live
installed then you'd also need:

sudo easy_install pygments idiopidae

You can also hit the http://launchpad.net/vellum/ page to grab source
tarballs and other goodies.


THE BOOK OF VELLUM

You can grab the most recent draft of the book at:

http://zedshaw.com/projects/vellum/manual-final.pdf

Any corrections or comments on how it is written are more than
welcome. Suggestions for improving the TeX are also helpful since I'm
not a TeX expert yet.

The software I'm using to build that book is fully available to anyone
looking to document their projects. You can grab Idiopidae, Pygments,
and TeX from the interwebs. You can then grab the whole source and all
the LaTeX goodness from my Bazaar repository:

bzr pull http://zedshaw.com/repository/vellum/

Look in the doc/ directory for all the fun. You'll notice that
the .tex files have *no* code in them, and that it's all imported by
Idiopidae. Look at the doc/book.vel file to see how it's all merged
and massaged together, and you can reuse this book.vel file to start
your own books.


CRAZY NICE WATCH FEATURE

I added a feature to Vellum that is one of those "duh" features. You
can tell Vellum to watch a file, and if it changes Vellum will rerun
some targets. When I work on the manual.tex file, I do this:

vellum -w doc/manual.tex book.draft book.view

It just keeps looping, and if you hit CTRL-C you can force a build with
ENTER or quit with CTRL-C. Then I use the evince PDF viewer under
linux, which has similar Vim key bindings and reloads the PDF when it
changes.

The net effect of this is, whenever I change my manual.tex file, Vellum
runs my build for the manual and evince redisplays it for me to see.

You could use this simple feature to also continually run unit tests
whenever a file changes that you are working on.

GPLv3?

How do people feel about Vellum's GPLv3 status? It actually doesn't
impact anyone unless you embed Vellum into a project/product or you
create commands (which you should give back anyway). Even then if you
never release your build to your users then you don't need to release
the commands.

However, I'm curious to get other people's thoughts.

Thanks a bunch folks.

 

[Michele Simionato]

However, I'm curious to get other people's thoughts.

For what concerns the license, I would say that GPL3 is fine:
for a tool basically any kind of license is fine,
since the tool is external to the code, so this is a minor point.
I am curious about two other things, though, perhaps answered in the
book but I had no time to read it all. First question: are you saying
that vellum does NOT keep track of already built files and recompile
everything each time, i.e. it is really in a different ballpark from
make and similar build tools?
Second question: what about docutils? A Pythonista would expect a
documentation tool to use reST and I am sure plenty of us out
there have articles/documents (even books) in reST and would be
interested in building them. OTOH I would not be interested in
learning yet another lightweight markup language or to go back to TeX.
Is the Vellum book written in reST?


Michele Simionato

 

[Istvan Albert]

You can grab the most recent draft of the book at:

http://zedshaw.com/projects/vellum/manual-final.pdf

However, I'm curious to get other people's thoughts.

IMO if you would refrain from using swear words in the manual it would
help broadening its reach and acceptance.

i.

 

[python]

Zed,

Read the first 2 chapters of your book and love it! Fun to read - I like
your writing style. I agreed with most of your premises/philosophies -
very refreshing.

I didn't find your language offensive but you might consider toning down
your review of the Awesome Window Manager

When do you plan on posting your next update?

Malcolm

 

[Ville M. Vainio]

GPLv3?

How do people feel about Vellum's GPLv3 status? It actually doesn't
impact anyone unless you embed Vellum into a project/product or you

Yeah, but it effectively prevents people from embedding it into their
apps that wish to remain BSD/MIT clean.

It's not likely that some evil corporation is going to hijack Vellum
source code as a basis of their next evil app (which is basically what
GPL is used to prevent) any time soon, so I don't really see a
particular reason for such a developer-oriented tool to be released
under GPL.

Basically, avoiding GPL maximizes the brainshare that a small-ish tool
is going to attract, and many (including myself, FWIW) view GPL as a
big turn-off when I consider spending some time to familiarize myself
with a tool, or recommending it to someone else.

 

[Ville M. Vainio]

I didn't find your language offensive but you might consider toning down
your review of the Awesome Window Manager

Nah - keep up the bad attitude. Your (Zed) blog/articles are one of
the few things on the programmosphere that actually make me laugh
audibly.

 

[Paul Boddie]

Basically, avoiding GPL maximizes the brainshare that a small-ish tool
is going to attract, and many (including myself, FWIW) view GPL as a
big turn-off when I consider spending some time to familiarize myself
with a tool, or recommending it to someone else.

I'd like to cast a vote for the opposing camp: I'm probably more
likely to look at GPL-licensed code, although I recognise that I have
the benefit of not having anyone superior to me wanting to release
proprietary software. Applications and tools are ideal candidates for
GPL-licensing, although I also recognise that someone might want to
adapt the code for a library, and that they might not feel comfortable
with the copyleft aspects of the resulting licence on that library.

Anyway, I'm just confirming that I'm clearly not one of the "many"
described above. A lot of my own work is licensed under the GPL or
LGPL, and while I'd be the first to admit that not much of what I've
written is wildly popular, I think the reasons for not using it purely
because of the licences are typically overstated.

Paul

 

[Ville M. Vainio]

Anyway, I'm just confirming that I'm clearly not one of the "many"
described above. A lot of my own work is licensed under the GPL or

I guess it's safe to assume that you are not opposed to using code
based on more liberal license, right?

My point is: GPL is a reason to reject a tool for some, but MIT/BSD
never is. Ultimately, of course, it's up to the preferences of the
author but if the idea is to maximize the popularity, GPL is a worse
bet.

 

[Paul Boddie]

I guess it's safe to assume that you are not opposed to using code
based on more liberal license, right?

As long as it's a GPL-compatible licence. ;-)

My point is: GPL is a reason to reject a tool for some, but MIT/BSD
never is. Ultimately, of course, it's up to the preferences of the
author but if the idea is to maximize the popularity, GPL is a worse
bet.

I know you were talking about small tools, but since we're being
jocular, I still can't resist the obligatory "tell it to Linus
Torvalds" remark.

Paul

P.S. I've actually released at least one work derived from a
permissively licensed work under the LGPL (and I did ask the original
author if he had any problems with that, out of politeness), mostly
because I didn't object to people building applications under a wider
range of licences, but I did want end-users to get the benefit of the
library source code, including any modifications.

 

[Ville M. Vainio]

Excuse the long post.

I'm less inclined to base work on, or contribute to, a work under a
non-copyleft license, because I have less assurance that the code will
remain free for all recipients.

In practice, the probability of hijacking of source code by an evil
corporation is very low for most projects. And even when it did
happen, the evil corporation would likely submit patches. The more
users an open source project has, the better.

Also, you can do what Paul Boddie did - fork the project, or maintain
patches that are under LGPL. With a liberal license, you have that
privilege.

There's no single free-software license that won't displease some
segment of the free-software community. I think the Vellum project

I don't think BSD/MIT like license really annoys anyone. Think python
here ;-)

I'm also answering some points by Zed here (assuming they were meant
for mailing list):

Well, I'm also telling people that it's like the GNU toolchain in that
using it doesn't mean your stuff is GPLed. Just if you import it as
a library or write commands for it that you release.

I realize this - there is a difference here between tools that you run
and tools that you link to / import. However, Vellum could be in the
middle ground, since the commands you create do link with Vellum.

Ok, so for you it's a religious thing more than a technical capability
or limitation thing? Does that mean you use a BSD alternative for
everything GNU, like GCC as well?

Not at all, it's a very practical thing related to all the
intellectual property lawyerage in corporate setting. With Vellum, it
doesn't matter a lot because most of the tools are only used in-house,
but it would still be nice if you could just grab the code from
somewhere without having to think about license at all, or considering
whether any of this would ever be needed for something that involves
selling stuff under proprietary license.

To stay on topic of Vellum, let's consider the scenario where someone
digged Vellum's syntax, and would like to use the parser in a
proprietary app - or create commands that include proprietary stuff
(it's not the developer's call, but the corporate policy). Vellum
parser would be only a small component in the whole system. Would you
rather make the developer:

- Find some other, inferior parser with more liberal license or
reimplement Vellum syntax from spec (typical "nah, this is gpl, I
can't use this, continue with the next google hit" scenario)

- Just grab the Vellum implementation and use it without concern or
management discussions, yielding yet another developer that saved some
time, had more coffee breaks and possibly hit the deadline early,
recommending Vellum code to his colleagues as a good starting point to
whatever they are doing, and perhaps contributing some code or ideas
back?

Note that this applies mostly to small tools / libs. Big projects like
Linux kernel, Gnome or KDE have to be seriously concerned about
malicious use of their intellectual property, but a small open source
tool is more likely to be (initially) picked up by an individual
developer who thinks something is cool; and it will never be the
money-making part of the product.

Also, for some reason, GPL is used for evil (dual-licensing schemes -
make money but still gain the open source mindshare, and possibly rack
up free contributions to something that is your *commercial product*)
more often than it's used for good (gcc, Linux kernel - prevent IP
exploitation and ensure that all improvements are freely accessible).

I must say that if I implemented something I want to make money on at
some point, I would license it under GPL. If I'm just scratching my
own itch, having fun or racking up open source feelgood karma, I would
use MIT (or BSD, as we are doing w/ IPython). So I'm not opposed to
GPL - just saying that it's not often the choice that will net you the
most users.

 

[Paul Rubin]

I don't think BSD/MIT like license really annoys anyone. Think python
here ;-)

Python's non-GPL license certainly is annoying to some of us.

 

[Matt Porter]

Python's non-GPL license certainly is annoying to some of us.

I'm intrigued - how can it be annoying?

 

[Carl Banks]

Excuse the long post.




In practice, the probability of hijacking of source code by an evil
corporation is very low for most projects. And even when it did
happen, the evil corporation would likely submit patches.

The Wine project changed from MIT (I think) to LGPL because evil
corporations were hijacking its source code and not submitting
patches. It happens.


Carl Banks

 

[Carl Banks]

GPLv3?

How do people feel about Vellum's GPLv3 status?

It's going to scare away some folks.

Using LGPL will almost certainly scare away fewer. People who don't
like GPL are usually concerned about its viral aspects moreso than the
requirement to contribute back released changes.



Carl Banks

 

[hdante]

Yeah, but it effectively prevents people from embedding it into their
apps that wish to remain BSD/MIT clean.

That's not a good argument. "GPL has the problem that if people don't
want to use GPL, then they can't use the GPL'd code."

GPL can mix with other free software licenses, so people who write
BSD code and do not wish to remain BSD clean are free to use GPL'd
code. That's the important point.

It's not likely that some evil corporation is going to hijack Vellum
source code as a basis of their next evil app (which is basically what
GPL is used to prevent) any time soon, so I don't really see a
particular reason for such a developer-oriented tool to be released
under GPL.

Viral licenses only serve that purpose ("protecting from evil
corporations"). If he licensed Vellum with GPL in the first place,
he's worried about that.

Basically, avoiding GPL maximizes the brainshare that a small-ish tool

True, but you may never ever see the brilliant result of that
brainshare work. Thus, for the author, your sentence is false.

is going to attract, and many (including myself, FWIW) view GPL as a

How many ?

 

[Paul Rubin]

I'm intrigued - how can it be annoying?

It means GPL'd contributions can't be included in the main Python distro.

 

[Paul Rubin]

if the idea is to maximize the popularity, GPL is a worse bet.

That is not a valid inference. Look at the popularity of Linux vs
BSD, for example.

 

[Paul Rubin]

How do people feel about Vellum's GPLv3 status?

I'm certainly in favor of it, though I didn't notice this question
until it spawned its own thread, and I'm not currently a Vellum
user or developer, so maybe my view shouldn't count for much.

 

[Paul Rubin]

In practice, the probability of hijacking of source code by an evil
corporation is very low for most projects. And even when it did
happen, the evil corporation would likely submit patches.

If they're going to submit patches then they shouldn't have any problem
with the GPL.

The more users an open source project has, the better.

That is simply not a valid premise, as others have explained. The
priorities of any particular project might give weight to the number
of users or might emphasize something else altogether. And some
projects are just plain bad (think of malware or spamming tools), so
it's better for the world in general if they fail and have no users
regardless of the developers' wishes.

 

[Carl Banks]

If they're going to submit patches then they shouldn't have any problem
with the GPL.

Nonsense. They could be more than willing to contribute their
patches, but aren't willing to accept the GPL's limitation to being
used only in open source packages.

LGPL? No, there is probably no reason to have a serious problem with
that if you're going to submit patches, but GPL, yes.


Carl Banks