diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/COMMUNITY | 16 | ||||
| -rw-r--r-- | docs/CONTRIBUTING | 57 | ||||
| -rw-r--r-- | docs/FAQ | 22 | ||||
| -rw-r--r-- | docs/INSTALL | 2 | ||||
| -rw-r--r-- | docs/TODO | 4 |
5 files changed, 73 insertions, 28 deletions
diff --git a/docs/COMMUNITY b/docs/COMMUNITY index f3159ad..7f86c7b 100644 --- a/docs/COMMUNITY +++ b/docs/COMMUNITY @@ -3,7 +3,7 @@ COMMUNITY ### Mailing list -* Address: uzbl-dev@lists.uzbl.org +* Address: [uzbl-dev@lists.uzbl.org](mailto:uzbl-dev@lists.uzbl.org) * [Page](http://lists.uzbl.org/listinfo.cgi/uzbl-dev-uzbl.org) * [Archives](http://lists.uzbl.org/pipermail/uzbl-dev-uzbl.org/) @@ -13,21 +13,21 @@ COMMUNITY ### Website -* http://www.uzbl.org +* [www.uzbl.org](http://www.uzbl.org/) ### Bugtracker -* http://www.uzbl.org/bugs/ +* [www.uzbl.org/bugs/](http://www.uzbl.org/bugs/) ### Code repositories Remember: dieter/master = official stable branch. If you want to develop, develop against dieter/experimental -* http://github.com/Dieterbe/uzbl/ -* http://github.com/anydot/uzbl/ -* http://github.com/Barrucadu/uzbl/ -* http://github.com/dusanx/uzbl/ -* http://github.com/robm/uzbl/ +* [github.com/Dieterbe/uzbl](http://github.com/Dieterbe/uzbl/) +* [github.com/anydot/uzbl](http://github.com/anydot/uzbl/) +* [github.com/Barrucadu/uzbl](http://github.com/Barrucadu/uzbl/) +* [github.com/dusanx/uzbl](http://github.com/dusanx/uzbl/) +* [github.com/robm/uzbl](http://github.com/robm/uzbl/) There are more contributors who have forks. See: diff --git a/docs/CONTRIBUTING b/docs/CONTRIBUTING index c88be30..14c3f0b 100644 --- a/docs/CONTRIBUTING +++ b/docs/CONTRIBUTING @@ -1,32 +1,58 @@ ### Users -Just use Uzbl, hang around in our IRC channel, try out different things and tell us when things break. -If you're feeling more adventerous, you can use one of the development branches and give bug +Just use Uzbl, hang around in our IRC channel, try out different things and report bugs. +If you're feeling more adventurous, you can use one of the development branches and give bug reports and suggestions straight to the developer in charge of that, so the same problems don't occur when they get merged into the master branch. Play around with the configs and scripts and see if you can improve things. The wiki can be a good source of inspiration. +You may also find mistakes in our documentation. ### Developers -If you don't feel like just sending bug reports, by all means dive into the -code and clone the code to start hacking. (github makes this really easy -with their "fork" concept). But it's usually a good thing to tell us first +If you don't feel like just sending bug reports, you can dive into the +code and start hacking. +Even if you're not good at C, thanks to uzbl's 'ecosystem' of scripts there +is a lot that can be done. +However, it's usually a good idea to tell us first what you want to do, to avoid unneeded or duplicate work. -Note that cloning and letting us pull (preferably via github) is way more -workable then submitting plain patches. Git is good in merging in branches -even if the base code has changed in the meanwhile. This does not work with -patches. +Read on for more info... -If you're new to Git/github, have no fear: +### Clone/patch/merge workflow -* [Github guides (highly recommended)](http://github.com/guides/home) -* [Guides: Fork a project and submit your modifications](http://github.com/guides/fork-a-project-and-submit-your-modifications) +1. clone the code with git. + Either you host your git repo yourself, or use something userfriendly + like [Github](http://www.github.com) + If you want to use github, you basically just need to register and click + the fork button on [Dieterbe/uzbl](http://github.com/Dieterbe/uzbl) + If you're new to Git/github, have no fear: -Our convention is to develop in the *experimental* branch, and keep only stable, tested stuff in *master*. -So ideally, all contributors develop in their experimental, that gets merged into the mainline experimental, and after QA it gets merged into the main master. + * [Github guides (highly recommended)](http://github.com/guides/home) + * [Guides: Fork a project and submit your modifications](http://github.com/guides/fork-a-project-and-submit-your-modifications) +2. Do your work, test it and push to your repo. It may be interesting to ask + others for input on your work. Make sure you do not develop against the + master branch! It is meant for stable, tested code. + All contributors develop in their experimental or other specific branches, + which get merged into the mainline experimental, and after QA it gets merged into the main master. + +3. If you think your code should be in the main uzbl code and meets all + requirements (see below), then ask Dieter to merge it. + + * send a mail to the mailing list with subject "`Pull request: <title>`" + with a short description of your stuff and link to your git clone and + which branch you're talking about. + We prefer you send us links to git clones, and not just patches. They + seem to be easier to merge, especially if the 'base code' has changed in the + meanwhile. + * If you really don't want to subscribe to the ML and only if it's a + small change, you can email Dieter personally. + * Please avoid sending private messages on github or asking Dieter to merge on IRC. + * If your patch is big, if it will help a lot if you can mention + that your code has been tested and is supported by other people. + +This is a relatively easy, solid and transparent way to handle all requests in order. ### Patch/branch requirements before merging: @@ -38,7 +64,8 @@ So ideally, all contributors develop in their experimental, that gets merged int Update them, not only for end users but also for your fellow hackers. * We recommend you finish your stuff first and then let Dieter know you want your stuff to be merged in, but we know for bigger changes this is not always feasible. Just try to keep the merges about bigger "clean changesets". - +* Your code should not introduce any compile warnings or errors. And also, + no regressions but that's harder to check. That said, you can always ask us to check on your stuff or ask for advice. @@ -4,8 +4,8 @@ FAQ ### I just installed uzbl but it doesn't do much. What now? Uzbl includes very limited default settings (statusbar settings, but no keybinds, history/download handlers etc.) Look at /usr/share/uzbl/docs/config.h to see the default settings. -Neither does uzbl create a default config file on startup like some other programs do because we want to give you the freedom to place your config where you want, and to use a config or not. Have a look in /usr/share/uzbl/examples/configs to see what you can do. + If you save a config as $XDG\_CONFIG\_HOME/uzbl/config it will be loaded automatically. Running with the `--verbose` flag on a command line can also be interesting. To get you started, try this: @@ -14,6 +14,26 @@ It will temporarily override your $XDG\_CONFIG\_HOME and $XDG\_DATA\_HOME variables so you can try the sample stuff directly in /usr/share/uzbl/examples. If you like what you can do, you can copy the sample stuff into your ~ and edit to your liking. +### Why don't you just use a reasonable config by default? +We actually did some attempts to make uzbl "usable by default" but in the +end we had to conclude it cannot be done because of the following reasons: + + * We don't want to store anything "automagically" in the users home. + Some people prefer different file/directory layouts, most of just want to + control the files in $HOME themselves. + * We considered the option of having a global '/etc/uzbl' which user + specific ones could override but that would overcomplicate things. + * We adhere to the [FHS](http://www.pathname.com/fhs/) (`man hier`), so + `uzbl -c /usr/share/...` is not an option. + +So even though we would like to make uzbl more usable by default, we think +there is no sensible way to do it. Maybe downstream packagers could provide +a note that users could copy the examples from /usr/share/uzbl/examples into +their homes, because really, that's all that is needed if you want it to +just "work" without controlling how yourself. (unless you have no +xdg variables set, in which case you should be smart enough to edit the sample +config yourself). + ### Where is the location bar? How do I change the URL ? Uzbl has no location bar. All changes to the uri (editing of current uri, typing new uri, loading of uri from bookmarks/history/...) happens *outside* of uzbl. Have a look at the sample scripts in /usr/share/uzbl/examples. Most of our examples use dmenu which is a nifty little tool to pick an item from a list of items (very diff --git a/docs/INSTALL b/docs/INSTALL index 43e139c..be6e85b 100644 --- a/docs/INSTALL +++ b/docs/INSTALL @@ -13,7 +13,7 @@ From source You can pull the code from git or get a tagged tarball. $ git clone git://github.com/Dieterbe/uzbl.git - [ $ git checkout master/experimental ] # optional. see below + [ $ git checkout origin/experimental ] # optional. see below $ cd uzbl $ make $ sudo make install @@ -12,7 +12,7 @@ More or less in order of importance/urgency * scrolling: make page up and page down configurable. * show % of location in statusbar/title if page doesn't fit entirely on view. * conditionals in format strings: eg if(SELECTED_URI) { "-> SELECTED_URI" } or another smart way to achieve the same. -* make default window size configurable, and optional +* make default window size configurable, and optional if this is not too much work * on uzbl.org commits overview: add date+time and repository * how to handle different content types? (text-plain, image/png, application/pdf,... maybe a map of content-type to uzbl/command xdg already has a spec for this i think @@ -40,7 +40,6 @@ More or less in order of importance/urgency * check for real command name, not just the first letter. * let users attach handlers to the most common events/signals in uzbl. great use case: automatically calling formfiller for certain sites -* write little script to open new urls with the urxvt url thing +document. * document: stylesheet overridding formfiller @@ -62,4 +61,3 @@ figure out how webkit intercepts key input make "disable insert mode" (esc key) configurable keywords don't work for external commands. is this a problem? * pass a bit less arguments by default, use the socket to query for them instead, or export the stuff through environment variables, or export them as xorg window properties -* write a config "generator" that iterates over the Uzbl uzbl and generates the commands needed to become in that state.
\ No newline at end of file |