Uncategorized


29
Jan 13

Curl cheatsheet

Curl is an awesome tool. I keep forgetting the switches though, so here’s a cheatsheet.

Simple GET request

curl -k "https://localhost/foo?bar=baz&abc=def"

JSON POST or PUT request

curl -k -H "Content-Type: application/json" -X POST -d '{"accountName":"test","value":"hello"}' https://localhost/foo
curl -X "PUT"

… for a PUT

POST a file

curl ... --data-binary @filename

Fake a /etc/hosts entry and a Host: header with curl

curl -vvv --resolve 'book.mixu.net:80:123.145.167.189' http://book.mixu.net/

Make a request with basic auth enabled

curl -vvv -u name@foo.com:password http://www.example.com

or:

curl --user name:password http://www.example.com

Set the Referer header

curl -e http://curl.haxx.se daniel.haxx.se

Set the User Agent header

curl -A "Mozilla/4.73"

or

curl --user-agent "Mozilla".

Set Cookies

curl -b "name=Daniel"

or

curl --cookie "name=Daniel"

Time a request (connect time + time to first byte + total tile)

curl -o /dev/null -w "Connect: %{time_connect} TTFB: %{time_starttransfer} Total time: %{time_total} \n" http://google.com

Downloading files from Github

curl -O  https://raw.github.com/username/reponame/master/filename

 

 


20
Dec 12

Restaurants in SF

I’ve been living in SF for quite a while now, so I figure I should list some of the restaurants that I like (the top ~45 to be exact). These are mostly places where you can get food quickly for lunch/dinner and that are walking distance from where I live.

Coffee

Philz Coffee. The best coffee in SF (in my opinion); the one closest to the center is on Van Ness (good if you go to the Tenderloin for lunch). The other Philz in the city center is at the Caltrain in SOMA (all locations). I always stop by when I’m close. Protip: don’t get the coffee with sugar, because they put too much and it detracts from the taste. Tantalizing Turkish, Aromatic Arabic and Soo Good (light roast) are my favorites.

Machine Coffee at 6th/Golden Gate is also quite good as are their sandwitches.

Blue Bottle. I would describe the coffee as artsy (as in “this coffee thinks it’s better than me”) – good for the occasional cup but I’m not a huge fan.

We have Peet’s coffee beans at the office so I haven’t really tried Peet’s at a store. In any case, these are all better than Starbucks, which is utter crap unless you get one of the specialty blends of the month rather than their regular coffees.

Japanese noodles

There are basically two good noodle places in the city center:

  • Ramen Underground (Union Square towards Financial District). RU is a short walk from Union Square. Their specialty is the spicy miso ramen. I recommend getting that with extra noodles and BBQ pork. Open on Saturdays as well.
  • Katana-ya (between Union Square towards Tenderloin). More choices than RU, including cold ramen and the toppings are better.

Expect to wait ~15 minutes. Suzu in Japantown is also good, on the other side of the walkbridge, downstairs. Once there, go to Moyo’s for some frozen yogurt.

If you have a car, drive to San Mateo, as there are some delicious noodle places there:

  • Santa Ramen (in San Mateo). Two words: premium pork! Mind-blowingly delicious.
  • Ramen Dojo (in San Mateo). Also very good. Prepare to wait in line though.

If you don’t have a car, get a Zipcar and drive. Seriously, it’s worth it.

Japanese curry

Muracci’s (Union Square towards Financial District) specializes in Japanese curry. I go there so often it’s ridiculous, only open till 6pm and only on weekdays though.

Kare-Ken (Tenderloin) is open after 5:30 till fairly late, however, their portions are smaller and the curry sauce isn’t quite as delicious as at Muracci’s.

Vietnamese sandwitches (banh mi)

These are a combination of Vietnamese -style veggies and meat in sandwitch form. Tasty and cheap.

  • Saigon Sandwitch (Tenderloin). The most famous banh mi place, this is for the banh mi snob. Their sandwitches are a bit spicier than the others and a bit smaller, but also taste slightly better.
  • Lee’s (Tenderloin). I like Lee’s as well, it’s across from Saigon. Their sandwitches are a bit bigger and they have more varieties, but the bread is less tasty.
  • Hoang Dat (Tenderloin). A smaller shop that’s up the street about two blocks. Nice if you don’t want to walk through the Tenderloin. Specialty is a sandine banh mi.

Outside Tenderloin, there are two other places I’d recommend:

  • Little Paris (Chinatown) is the place to go if you want Vietnamese sandwitches in Chinatown. I love this place and I was happy to find that they reopened (they moved about six months ago).
  • Fresh Brew Coffee (Union Square) is a small coffee shop closer to Union Square where you can get banh mi with avocado in it. It is expensive compared to the Tenderloin or Chinatown, but bacon and avocado are a winning combination.

Other kinds of sandwitches

  • HRD Coffee Shop (SOMA) is awesome. They have really great sandwitches, and their specialty are the sandwitches with Korean spices. I miss living in SOMA.
  • King Foot Subs (Union Square;  Bush and Powell) offers similar sandwitches, though they aren’t quite as good as HRD. They are open late, however.
  • Molinari’s (North Beach). Prosciutto sandwitches, need I say more?
  • Morty’s Delicatessen (Tenderloin). Really delicious deli sandwitches.
  • Miller’s East Coast Deli and Freddie’s Sandwiches are near each other, I like Freddie’s a lot and Miller’s has a good pastrami sandwitch.
  • Cafe Venue. Next to the Westfield Mall, really big salads during lunchtime, usually enough for two meals.

Chinese dumplings (dim sum)

There are hole-in-the-wall type places where you can get two meals worth of food for 6-8 bucks:

  • Good Mong Kok Bakery. This is where all the Chinatown locals queue up, and it is good.
  • Delicious Dim Sum. More accessible than Good Mong Kok, also good, very close by to Good Mong Kok.

Chinatown protip: there are small side streets that mostly avoid the crowds, use them if you don’t feel like dodging people.

Vietnamese

Pho = thin noodles with a ligher soup and veggies. The vermicelli noodle salad with spring rolls is also delicious. Check out:

  • Pho 2000 (Tenderloin): big portions, good stuff.
  • Pho Tan Hoa (Tenderloin/Union Sq): closer to Union Square, fast service, big portions of pho.
  • Miss Saigon (~6th). Sketchy neighborhood but the food is good.
  • Tu Lan (~6th). Delicious, but closed down until ~2013. Tu Lan is legendary, but it was closed for repeated health code violations so I’m not sure I’ll go there very often when they reopen.
  • Loving Hut (Westfield Mall but also Chinatown). One location is in the Westfield Mall and I’d guess this is healthy food. Fully vegan, but I couldn’t tell. I always get the vermicelli noodle salad with spring rolls.
  • Cordon Bleu Vietnamese Restaurant (~Union Square). When you don’t feel like walking into the Tenderloin, and want a lot of food to go. Their portions are epic, though the place is a hole-in-the-wall and not the most delicious. Get the vermicelli salad thing, the rice in the rice dishes has been cooked too long in my experience.

Thai food. Koh Samui and the Monkey in SOMA is nice. There is a corner on Jones and Post in the city center that has like 4-5 Thai places, but they are all quite similar in quality and price so nothing stands out. The lunch special at the Old Siam Thai Restaurant in the city center is decent.

Duck noodle soup. Hai Ky Mi Gia (Tenderloin) the duck noodle soup here is mind-blowingly good.

Mexican. I got a pretty bad food poisoning a while back so I’ve been avoiding Mexican food ever since. Really, you’d need to live in Mission to become an expert. Taqueria Cancun (6th and Market) is OK.

Turkish. Gyro King (Civic Center) is a good place to stop by for a pita kebab. It’s one of two Turkish places in the city center.

Food trucks. Chairman Bao (Food Truck). The best food truck I’ve tried so far. KoJa is also good, try the dessert cake if you see it. Other than that, food trucks are a scam in that you pay more for less food – it’s a hipster tax.

Korean. Sorabol in the Westfield is mall food, but definitely one of the better places in the Westfield mall. Dong Baek Restaurant in the Tenderloin is decent, mostly for variety; it is open late and you’ll get a ton of those small side dishes with every meal.

Indonesian. Borobudur Restaurant is the only game in town, get the pancake thingy from the appetizers

Middle Eastern. In general, my problem with middle eastern food is that the restaurants feel understaffed and it takes too long to eat. Yemeni’s Restaurant is nice, just don’t get the Yemeni thing, it’s too weird (spinach soup with meat?). Tayyibaat Meat & Grill also hits the spot and is easier for takeaway.

If you need fried chicken, go to Louisiana Famous Fried Chicken.

If you want to just eat steak, go to Espetus Churrascaria for some Brazilian steaks – the lunch prices in particular are cheaper and you’ll get all the meat you can eat.

Indian/Pakistani

So, there is a whole concentration of Indian/Pakistani between Geary and O’Farrell on Jones St.

Here’s my ranking: ShalimarKarachi Classics, Pakwan, Chutney.

  • Shalimar, is delicious but the service is bad, they make you wait and don’t acknowledge you until they feel like it. Which is why I often prefer to go to Karachi Classics.
  • Karachi Classics is usually fast and quite good, though they have a much more limited selection.
  • Pakwan has better service, but the curry isn’t quite as delicious.
  • Chutney has consistency been a bad experience for me (service and food), so I’d recommend against going there.

Also, Dosa on Valencia is good.

Burgers.

  • Pearls Deluxe. Two locations, one on 6th and Market, the other near the Thai restaurant block on Jones St. Protip: get the regular burger, also try the milkshakes,  they are really good
  • Super Duper. Around 3rd and Market, good burgers
  • In’n’out. Google the secret menu and get a really big burger. There are no convenient locations though; the only one in SF is near the tourist trap known as Pier 39.

Cuisines I have no clue about:

  • Italian. I’m yet to find a decent Italian restaurant in SF. The places I’ve been have been acceptable, but not great. I’m still looking for a really good Italian place.
  • Pizza. All the pizza I’ve had has been totally forgettable: not bad, not amazing.
  • Kebab with french fries. In the US, kebab is way too rare, I want take-away hangover food not fancy restaurant food.

Hey! Leave a comment if you think of a restaurant I’ve missed that is really good, I’ll go try it out.


26
Jul 12

Writing about technical topics like it’s 2012

For some reason, a lot of technical writing is still done as if the reader didn’t have access to the Internet. Having written two books (Mixu’s Node book and Single page apps in depth) in the past year, I’ve had some time to think about what good technical writing might be. There are several things that could be improved:

1.  Assume the reader has Internet and Google capabilities. Skip the parts that are covered better elsewhere or that will go out of date quickly. For example, installation tutorials are never up to date. I’ll generally skip the sales pitch for the technology as well, since I’m here to tell you about the tech, not sell you on using it.

2. Keep it short and to the point. I hate books that try to be cute or clever with me – if I want a story, I’ll go read fiction. Similarly, don’t surprise the reader with irrelevant sections. Just because you wrote it doesn’t mean it should exist. I keep a crap file where all the useless text goes, and I usually have a couple of chapters worth of text that I delete. I’ve written several chapters on the history of a piece of tech, and always deleted them in the end.

3. Use teasers, lists, tables and code blocks. Assume that the reader can get bored quickly, so throw in something interesting quick (a teaser) and support skimming readers with subheadings, lists and other structural elements.

4. Don’t treat everything as equally important. The easiest way to write a book about a piece of tech is to take the API, and then cover each and every function in it. It’s also the worst possible way to do it. Unless you are writing the API docs, you should avoid talking about everything and focus on the interesting parts.

As a reader, if I want to find out more, I can always read the API or code. What is much more important is understanding what are the neat things that I can do with the new tech, what kinds of patterns are common in using it and why you as the author think they are good or bad. Talk about how the pieces fit together. If everything is equally important, then nothing stands out. I like getting the author’s angle on things, even if I might disagree with their choices, I still feel like I gain insight.

5. Give me a choice in formats. Provide HTML, PDF, epub and mobi versions of long texts. Converting html for the Kindle just requires running one command with Calibre, so I wish more authors gave me the option to download their writing. For example, I wish I could get Google’s tutorials for Android as a Kindle mobi book, since that’s how I like to read long form writing.

6. Help me navigate.  Often, when I like what I read, I’ll want to read more. Don’t force me to go page by page through your writing. If you have a blog, have an archive that can show all the content, and let me get an idea of what else you’ve written about at a glance (a most popular list always helps).

More about writing:

http://www.paulgraham.com/writing44.html

http://bighow.com/news/the-art-of-great-writing-60-writing-tips-from-6-alltime-great-writers

http://dannystack.blogspot.com/2009/01/joss-whedons-top-10-writing-tips.html

 


6
Jun 11

Hello San Francisco!

If you’ve been wondering why I haven’t been writing much on the blog recently, here is why: I just got my visa to the US and moved to San Francisco for an internship! I’ll be here for the next 12 months on that visa. That process + wrapping up my life in Finland took a lot of my free time, the rest went to reviewing a coming-soon Kohana 3 book from Apress for which I’m a technical reviewer, and my writing project related to Node.js which I am hoping to move forward soon. I also gave a talk at Frontend.fi on Node (my first tech talk), and released a small library (node-winamp) to control Winamp over LAN from the console using Node.

My new years resolution was to ship more, but I never expected to ship my own ass over to San Francisco! It’ll be awesome.

I flew in on June 3rd, and have been here for two days. So far, everything has been pretty awesome, though I still need to find an apartment rental and get the final paperwork done on this side!

Since I’ll be able to concentrate more on code instead of living the triple life of a doctoral student, individual entrepreneur and open source programmer, I hope to start building a solid streak of open source/fun coding while I’m here. I read something on HN recently which I think will be good to keep in mind:

“I have a rule: I refuse to go to sleep if I haven’t read and written some code on a given day (this doesn’t include the code I write for work, of course). So far, this rule has had a positive impact on my ability to code.”

I’ll try to apply that rule, perhaps using 42goals.com or the Calendar About Nothing

 


15
Nov 10

How to install gnome-color-chooser for Fedora

Gnome-color-chooser is a tool which allows you to control the colors used in GNOME with a lot more granularity than the default “Appearance” app.

Unfortunately, Fedora does not have a repository with a gnome-color-chooser rpm, so you will need to compile it yourself.

Here are the instructions, tested with gnome-color-chooser v. 0.2.5 and Fedora 13/14:

su
yum install wget gcc-c++ glib-devel intltool gtkmm24-devel libglademm24-devel libgnomeui-devel libgnome-devel libxml2-devel
 
wget http://downloads.sourceforge.net/project/gnomecc/gnome-color-chooser/0.2.5/gnome-color-chooser-0.2.5.tar.gz
 
tar -xzvf gnome-color-chooser-0.2.5.tar.gz
 
mv gnome-color-chooser-0.2.5 /opt/gnome-color-chooser
 
cd /opt/gnome-color-chooser/
 
./configure
 
make
 
make install

After installing, you can find it under System -> Preferences -> Gnome Color Chooser.


5
Nov 10

4 simple ways startup people deceive themselves

One of my many favorite quotations is one from Demosthenes: “Nothing is easier than self-deceit. For what each man wishes, that he also believes to be true”. Nietzsche puts it in another way: “The visionary lies to himself, the liar only to others”.

Startup people really need to be a bit nuts in order to get anything to done. I was reminded of this today while reading this Hacker News thread. Please note that I am not writing this as criticism to this particular founder, I am certain the same criticisms apply to myself and many others.

There are a number of beliefs that are useful and false that startup people need to/tend to hold:

1. The prerequisites-will-save-me belief

You remember how going to college you were told that getting your degree will be useful in getting a job? Especially now that the economy isn’t great, I’ve seen tons of people complaining about how getting a degree did not guarantee that they got a job. Of course, that was not the actual claim – it was only implied that filling in the prerequisites would lead to success.

Starting something new, you have to believe that filling in the prerequisites for success (whatever those are: an extensive plan, a completed prototype, an encouraging response) will be sufficient for actual success. There are so many things that are out of our hands that all we can do is to do our own part and hope/believe that that will be enough, since there are many things that you cannot influence effectively. I have done the prerequisites, so I must get – nay, I deserve – funding, traction and all the other good things.

It isn’t false that doing the right prerequisites is necessary. It’s just that doing the prerequisites is not a guarantee for anything; and that knowing what is the right thing to do is hard.

2. The idea-is-important belief

I see this a lot among founders, particularly non-technical founders. It states that all you need is great idea, and everything else will fall into place. How long can it take to create and launch a product now that I have a great idea? The origin of this belief is that we tend to underestimate the amount of work and persistence needed, particularly for those things that we have little or no experience doing.

For non-technical founders, it’s the part where you take a rough idea and make it into something that actually works and is nice to use – which implies a million small details that have to be done correctly and which always takes longer than expected. For technical founders, it’s the part where you get someone to care about what you are doing: whether this is getting funding, or getting traction with partners, or getting someone to buy your product. We tend to like to think that whatever we do not understand must not be particularly hard or time-consuming.

It isn’t false that a good idea is useful; indeed, there are tons of examples of a simple, insightful idea leading to huge success. It’s just that those ideas are outliers: if they weren’t, we wouldn’t consider them so remarkable. VC’s say the invest in the team, not the idea – which probably is both true to some extent and false to some extent.

If you hold this belief strongly, then you tend to be secretive of your idea. Here is a thought experiment I came up with a while ago: Give someone the lottery numbers for next week. See if they act on it. They probably won’t. In fact, try to convince them that you have some strange scheme that allows you to know the lottery numbers. I’m not saying startups are a lottery, it’s just that you are claiming to have some extremely valuable idea based on some chain of logic. You’ll still have a hard time convincing people, let alone getting them to part with their money.

If you don’t love your idea, you won’t have the persistence to make it work. But at the same time, in retrospect, most ideas are garbage.

3. The can’t-do-it-without-money belief

This is frequently associated with potentially game changing startups (=founders believe it is potentially game changing). The assertion goes something like this: I have all the other parts, now I just need someone to add money in order to make the next big thing. This is also the reason why VC funding exists, and does make profit for some people.

This may or may not be correct; there are many companies that need funding in order to reach a sustainable size, or to capture an early market. And you might be one of those companies, which means that you need to take an extremely proactive approach to getting funding.

The problem with this belief is, however, that there are still many variations of ideas that can be done with less capital, and I do believe that you should believe enough in your company to do whatever you can whether or not someone pays you a “salary” to do something. Yes, you can do a lot more if you can focus and not worry about money, but VC’s aren’t a charity – which implies you should do what you can to achieve traction before deciding not to put in more time without funding. At the same time, you need to recognize when you have done all you can without money, and then decide whether to move on.

Of course, how much you should do before calling it quits is hard to answer – perhaps you have done everything you can to polish the concept and raise funding, and should call it quits, or perhaps funding is waiting just around the corner?

4. The persistence-is-omnipotent or I-will-make-it belief

This is the belief that iterating on a product will eventually lead to something successful. Since traction is rarely instant, it is rather useful to believe that whatever issues have come up so far can be solved in the next iteration of the product. Famously, PayPal started as a service reconciling beamed payments from Palm Pilots with email payments as a feature till they realized what they should be doing.

But despite the fact that you are smart and special, most startups statistically fail. And believing that you can make a turd work will probably just waste your time. Satisfaction with the current situation and expected progress is a prerequisite for wasting time.

“No matter how far down the wrong road you’ve traveled, always turn back.” But of course knowing whether you are on the wrong road is hard, and it just might be that keeping the idea alive for another week will result in traction. Or not. You won’t know, unless you believe that you should try.

Conclusions

What is interesting about these beliefs is that they are both useful and harmful: both true and false depending on what the exact situation is.

Confidence doesn’t directly influence your success rate, but it raises your attempt rate. And as Wayne Gretzky said, you miss 100% of the shots you never take.

Most people are overly preoccupied with the costs and risks of doing something. Entrepreneurs have to be optimists by nature, but try not engage in (too much) self-deceit. Edward Benson put it this way: “How desperately difficult it is to be honest with oneself. It is much easier to be honest with other people.”


6
Oct 10

Tip: Disable CakePHP model auto-load and trace the load paths

Here is how to disable the model auto-loading in CakePHP:

// .. around line 140 in /cake/libs/class_registry.php
} elseif ($type === 'Model') {
   if ($plugin && class_exists($plugin . 'AppModel')) {
      $appModel = $plugin . 'AppModel';
   } else {
      $appModel = 'AppModel';
   }
   $settings['name'] = $class;
   $ai =& App::getInstance();
   $search = $ai->__paths('Model');
   $pathstr = '';
   $file = Inflector::underscore($class.'.php');
   foreach ($search as $path) {
      $path = rtrim($path, DS);
      if ($path === rtrim(APP, DS)) {
         $recursive = false;
      }
      if (true === false) {
         $pathstr .= $path . DS . $file.'|';
         continue;
      }
      if (!isset($this->__paths[$path])) {
         if (!class_exists('Folder')) {
            require LIBS . 'folder.php';
         }
         $Folder =& new Folder();
         $directories = $Folder->tree($path, false, 'dir');
         $this->__paths[$path] = $directories;
      }
      foreach ($this->__paths[$path] as $directory) {
         $pathstr .= $path . DS . $file.'|';
      }
   }
   die("unable to find class $type, $plugin$class "
   ."(search path: ".$pathstr.")");
   ${$class} =& new $appModel($settings);
}

25
Jul 10

Kohana3: Setting up phpUnit and phpDocumentor

Here is my quick guide on how to setup phpUnit and phpDoc for Kohana 3.

phpUnit

1. Setup

Install phpUnit using pear:

pear install phpunit

(See the PEAR site for how to install PEAR.)
Get the Kohana unittest module from http://github.com/kohana/unittest. If you aren’t using git for your repo, just clone the files (git clone http://github.com/kohana/unittest.git), get rid of the .git subdirectories and copy the module to your modules/ directory.

Follow the setup instructions on GitHub. Some tips:

It may be easiest to define an alternative default database configuration, since currently unittest does not automatically change any of the database configurations (ex. in models). Since I use a Fedora VM for development but prefer to run tests on Windows, I added the following logic to config/database.php:

if (strtoupper(substr(PHP_OS, 0, 3)) === 'WIN') {
return array('default' => ..test config..);
} else {
return array('default' => ..normal config..);
}

I did the same thing in bootstrap.php, selectively enabling the unittest module and changing the cache dir based on the OS. You can probably think of some way to do the same in your setup even if you aren’t using a different OS for serving HTTP requests.

2. Creating tests

Tests for application files go into the application/tests/ folder you create.

Tests for any module (inc. application, database, unittest etc.) go in the ‘tests’ folder in the module.

Tests extend Kohana_Unittest_TestCase, not PHPUnit_Framework_TestCase.

To group individual tests into modules you need to add the tests to a group for that module. The convention for group names is modules.{module_name}. This is done using the docblock @group specification (can have multiple group specifications). See Writing Tests in the repo on GitHub.

3. Fixtures

The easiest way to create fixtures is to use setUp() to set the DB, then tearDown() to clean up. You can just use the DB class, or use ORM to add the records. Example:

class WhateverTest extends Kohana_Unittest_TestCase {
   function setUp() {
      // setup the DB
      DB::query(NULL, "TRUNCATE `kohana_test`.`whatever`;")->execute();
      $fixture_rows = array(
          array(
            'key' => 'billing_key',
            'value' => '0',
          ),
      );
      // add the necessary items
      foreach($fixture_rows as $row) {
         DB::insert('whatever', array_keys($row))->values(array_values($row))->execute();
      }
   }
   function tearDown() {
   }

There is probably a better way using a proper fixture class, but I haven’t seen one for Kohana yet.

4. Execution

You will need to specify the path to the KO3 webroot index.php as the bootstrap for phpUnit. This is because the dependencies which your code has need to be loaded by Kohana.

By default, all tests in application/tests/ will be run.

phpunit --bootstrap=index.php ./modules/unittest/tests.php

To run a specific group of tests on the cli add –group {groupname.in.testfile} between the –bootstrap switch and the path to the tests folder.

phpunit --bootstrap=index.php --group groupname.in.testfile ./modules/unittest/tests.php

phpDocumentor

Install phpDocumentor using PEAR: pear install phpDocumentor.

On Windows, if you use paths with spaces in them it is easiest to make sure that phpDocumentor is in the php include path (edit php.ini if necessary), and invoke php while passing the phpdoc file directly (see below for example).

You will probably only want to generate API docs for application/, perhaps selectively adding a few modules. And you probably want to exclude: application/vendor/, application/logs/, application/views/, application/bootstrap.php and application/config/ from the API documentation.

Remember that phpDocumentor does not support multiple option specifications: you have to join the paths with a comma. Furthermore, remember to have the directory separator character at the end of directories to trigger the correct interpretation.

Kohana3 uses a number of custom tags, so you will want to exclude those. Here is a sample run:

php "c:Program Files (x86)PEARphpdoc" --directory application/
--ignore application/vendor/,application/logs/,application/views/,application/bootstrap.php,application/config/ --target doc/api
--customtags type,default,constructor,chainable,class,namespace,module,group

There are a few options that may also prove useful:
–parseprivate causes private methods to be shown
–output HTML:frames:earthli changes the output to earthli, which I like.
–undocumentedelements Adds warnings to errors.html for undocumented elements.


20
Jul 10

Better web application interface markup: lessons from theme frameworks

Every time I start a new web application project, I spend a while (re)thinking what the layout structure should be in terms of CSS and HTML (e.g. semantic naming, organizing CSS markup).

Recently, I did a project using the Thematic theme framework for WordPress, and that got me thinking about how custom web applications interfaces could be improved. As an individual developer, I rarely have the luxury of focusing on the details of the layout. In contrast, the developers building theme frameworks have spent years thinking about how to create a generic, extensible structure for web application interfaces.

I had a look at Thematic, WP-Framework and Theme Hybrid (see more frameworks in this Smashing Magazine article). I used Thematic, since I ended up using it in the WordPress project I did. Here is how Thematic does it’s HTML layout:

An overview of the HTML code (based on Thematic)

I think the most interest parts of Thematic for web application design are the HTML structure, use of ids and classes and the CSS files. The hook-and-filter system (overview here) is less interesting from the web application point of view, since you will most likely be writing all of the code from scratch for your own web applications.

<!doctype html>
<html>
   <head>
      <title></title>
      <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   </head>
   <body>
      <div id="wrapper">
         <!-- Header -->
         <div id="header">
            <div id="branding">
               <div id="blog-title"><span>...</span></div>
            </div>
            <div id="access">
               <div class="menu">
                  <ul>...</ul>
               </div>
            </div>
         </div>
         <!-- Main -->
         <div id="main">
            <div id="container">
               <div id="content">
                  <div>...</div>
               </div>
            </div>
            <div id="primary">
               <ul>...</ul>
            </div>
         </div>
         <!-- Footer -->
         <div id="footer">
            <div id="siteinfo">...</div>
         </div>
      </div>
   </body>
</html>

1. Body and wrapper

In all of the frameworks, the body classes contain various information such as the platform (windows) and the browser (firefox, ff3).

Benefits:
Easier to specify per-browser css fixes (if needed). This makes it easier to make adjustments based on the browser or OS used in CSS, eg. “.windows xxx.yyy { … }”.

Separation between body and content wrapper. In the framework, the content is wrapped in a wrapper layer (id=wrapper), so that the body has only one child element. I would imagine this is to make it easier to use CSS to adjust the padding and background of the pages.

2. Heading

The heading consists of two sub-divs, as shown below:

There are only three subelements to the content wrapper: heading, main and footer. Each of these divs is full-size and positioned relatively.

Benefits:
Easy to add repeating backgrounds. One can easily apply a CSS background-image to create a repeating and consistent heading.

Easy positioning of the elements. The heading consist of the branding and access divs. This makes it easy to add new heading elements in the branding, while keeping the menu (=access div) separate, with it’s own background.

Standard menu HTML. All of the frameworks appear to be using the Superfish menu by default, which is based on jQuery.

3. Main content

The main content consists of a container with a content-sub-div and a primary sidebar:

The main content div has a fixed size. This is then subdivided into two divs, container (for the content) and primary (for the primary menu block).

Benefits:
Semantic markup; floats to reposition Having these separate divs means that switching from “menu on the right” to menu on the left is simple, since one can change the CSS float directions to reverse the positions of the subcontainers.
Easy to add new content areas One could also add more subdiv for additional content areas, and create multiple columns relatively easily by positioning the subdivs within the main content div.
Easy to add sub-items The primary menu is a div, with each block having its own unordered list (ul). In practice, this leads to two levels of lists – one for the item blocks themselves, the other for the sub-items (e.g. the links in a Archives block).

4. Footer

The footer consists of a single subdiv:

Again, the top-level div only specifies the margin, while the inner divs are positioned within it. This makes it easy to add a background to the footer div.

Does this work?

I’m currently using this approach in recent two web applications I built. The markup seems a lot cleaner, more standard and I have found that re-theming the same basic HTML is much nicer than reinventing the wheel. In short, I think this is a good approach. Let me know if you have improvements via a comment.

Somewhat related: What about other techniques, such as CSS Grid frameworks or Haml/Sass?

I’m not yet convinced that I need to use a CSS Grid framework (e.g. Stackoverflow discussion).

As for Haml, I’m pretty sure that I am fine with regular HTML without any syntactic sugar.

Sass seems to be a real improvement over CSS (variables, nesting, mixins etc.), but on the other hand I haven’t had the time to set it up with my non-Ruby environment.


10
Jul 10

Quick tip: Netbeans is excluding / ignoring directories in version control

Is Netbeans not showing the version control options correctly for some of your directories? Check whether you have accidentally left .svn directories. All source control system directories are hidden by default in Netbeans, which makes spotting this a bit tricky.

Check for whether there is a another repo, e.g. a .svn directory somewhere in your path. Netbeans seems to allow “stacking” source control systems, and will unsuccessfully try to load this versioning data instead of whatever you are using in your repository. This means that you won’t get those pretty markers for modified lines and won’t be able to view history for those files or perform a diff from the Netbeans GUI.

See ~/.netbeans/$version/var/log/messages.log for debugging information. Look for messages related to source control loading failures.

Get rid of the extra directories (e.g. .svn in each directory) in your repo, and delete ~/.netbeans/$version/var/cache/svncache to avoid conflicts with cached incorrect versioning data.