/srv/irclogs.ubuntu.com/2010/02/23/#ubuntu-classroom.txt

=== kermiac_ is now known as kermiac
=== mhall119|SCaLE8x is now known as mhall119|work
=== kermiac is now known as kermiac_
humphreybcum04:00
humphreybci have a voice!04:00
=== ChanServ changed the topic of #ubuntu-classroom to: Welcome to the Ubuntu Classroom - http://wiki.ubuntu.com/Classroom || Support in #ubuntu || Upcoming Schedule: http://is.gd/8rtIi || Event: 48 Hours of Ubuntu Manual Learning - Current Session: An introduction to the project - Instructor: humphreybc || Questions in #ubuntu-classroom-chat
humphreybc[SLIDE 1]04:00
humphreybchttps://wiki.ubuntu.com/ubuntu-manual04:01
humphreybcCan i have a show of hands for who's actually here?04:01
=== epkugelmass is now known as Guest45531
humphreybcwe'll wait another 2 minutes for some stragglers to arrive04:02
humphreybcokay so those who aren't using Lernid, you can get the slides from  http://kevin.godby.org/ubuntu-manual/talks/04:04
humphreybcAlso, you can chat in #ubuntu-classroom-chat04:04
humphreybcbecause you're not voiced in this chatroom04:04
humphreybcand lastly, to use the ClassBot question feature, ask a question in the chatroom and preface it with "QUESTION"04:05
humphreybceg, "question: why are you telling me all this even though I already know it?"04:05
humphreybci'm going to assume everyone's happy and i'll move on!04:05
humphreybcyou can ask a question whenever you want btw04:05
humphreybcokay so, the ubuntu manual project04:06
humphreybcwhat the project is about. [SLIDE 2]04:06
humphreybcwhat we're trying to do is create some great documentation that's easy to follow and all in one place04:06
humphreybcI used to be an Ubuntu beginner once04:07
humphreybcand basically when I started I found the help to be quite hard to find, our out dated04:07
humphreybcthat's nothing against the docs team, they're doing the best they can and it's hard to maintain docs04:07
humphreybcso what we're trying to do is create an up-to-date comprehensive manual that's in a context for fairly new people to Ubuntu and computers in general04:08
humphreybcWe'll re-release a version every 6 months to coincide with Ubuntu releases04:08
humphreybcat the moment we're obviously working on the Lucid release04:08
humphreybcThe project itself only started a couple of months ago with just me writing the document myself. I originally was going to make it closed-source but free, 50 pages or so, not a huge amount of screenshots, in open office and only in english04:09
humphreybcbut some ubuntu community members advised me to open it for collaboration on launchpad04:09
humphreybcSo i did04:09
humphreybcturned out that a lot of people felt that a manual like this was really needed04:09
humphreybcso now we have 250+ contributors, working towards a 200 page manual with 50 screenshots translated into 40+ languages04:10
humphreybcinstead of using open office we write it using latex04:10
humphreybc[SLIDE 3]04:10
humphreybcWho it's for04:10
humphreybcWe're targeting people who have possibly used a computer before on either Windows or Mac04:11
humphreybcwe expect them to know what a mouse is and we expect them to have basic computer skills - enough to be able to acquire the manual in the first place04:11
humphreybcbut from then on, our manual is written assuming they've never heard of Ubuntu or Linux04:11
humphreybcso we give an introduction to Ubuntu/Linux, history of it, talk about the community and FOSS software etc in the prologue04:11
humphreybcwe teach them everything they need to know to get stuff done04:12
humphreybcbut we don't teach them too much04:12
humphreybcour target audience view computers as a "means to an end"04:12
humphreybcthey don't want to know how it works, they just want to know how to get stuff done, like print or send emails or view photos :)04:12
humphreybc[SLIDE 4]04:13
humphreybcSo basically What we want to achieve - i've sort of covered this already04:13
humphreybcour goals are inclusion on the default CD at some stage, and definitely in the repositories.04:13
humphreybcwe want to give the reader many choices with regards to language, format, layout, paper size etc04:13
humphreybcso in the future we're planning an HTML5 version, paper sizes will be attached to languages (en_US will be US Letter size, en_GB will be A4 etc)04:14
humphreybcand we're going to create a nice website with an easy way to acquire the right manual. probably just three questions that they answer, like "what language do you speak" "what country are you from" and "what distribution would you like the manual for"04:15
humphreybc(we might do a Kubuntu/Xubuntu/Ubuntu Netbook Edition/Ubuntu Developers Manual etc down the line, depending on the success of this one)04:15
humphreybcokay, so, any questions on all of that before I move on?04:15
humphreybc(questions can be asked in #ubuntu-classroom-chat)04:16
humphreybcnope?04:16
humphreybcokay, moving on04:16
humphreybc[SLIDE 5]04:16
humphreybcso that's all well and good I hear you say, but _how_ is all this going to happen?04:17
humphreybcwell, we are using a bunch of existing tools and creating our own tools in some instances04:17
humphreybcbasically the manual itself is written using LaTeX 2009, in .tex files that are compiled into a PDF (and down the line, other formats like HTML5)04:18
humphreybcwe use Launchpad for blueprints, code hosting, milestones, bugs, answers and translations04:18
humphreybcWe use Bazaar for version control, and the Ground Control application as a GUI front end to bzr04:18
humphreybcWe use Launchpad's rosetta system for translations, and po4a to take the strings out of the .tex files and put them into .po and .pot files04:19
humphreybcwe use several methods of communication, namely, IRC channel (#ubuntu-manual), mailing list, wiki, weekly meetings, facebook, msn, skype04:19
humphreybcwe also have an aggregated blog: http://planet.interesting.co.nz04:19
humphreybcWe thrive on publicity and hype, and we have ambitious goals04:20
humphreybcbut we have a fast paced development environment04:20
humphreybcthere isn't much stuffing around, we just "get things done."04:20
humphreybc[SLIDE 6]04:20
humphreybcWho the key people are04:21
humphreybcI won't repeat what's on the slide here because you should be able to see it04:21
humphreybcbasically there are 6 key people04:21
ClassBotvdquynh asked: on which server is the #ubuntu-manual channel (I'm connected and searching irc.ubuntu.com)04:21
humphreybcirc.freenode.net :)04:21
humphreybcsorry I should have made that clear04:22
humphreybcso 6 key people, myself, project leader, dutchie who does a tonne of backend stuff, godbyk who does the latex stuff, Ilya, who works with the authors, Jamin who coordinates editing and thorwil who does the artwork04:22
humphreybcwe also have a small team of developers working on Quickshot (i'll explain what Quickshot is soon)04:23
humphreybcby the way, these slides are all available in our bzr branch lp:ubuntu-manual04:23
humphreybc[SLIDE 7]04:23
humphreybcOkay, Quickshot!04:23
humphreybcSo, basically, in our manual we have around 50 spaces for where we'd like to put screenshots04:23
humphreybcand we want all the screenshots to be localized (no use putting an english screenshot in the chinese manual)04:24
humphreybcso, 40 translations04:24
humphreybcthe math is 50 x 40 = 2000 screenshots04:24
humphreybcwe also need the resolution, theme, applications, dpi, file format, file name etc to be consistent so we can work well with them in LaTeX, and also so it looks good04:24
humphreybcit would take years for a few people to get all these shots themselves, and it would be very very inefficient and time consuming04:25
humphreybcso i came up with the idea to write a program that automates a lot of the stuff04:25
humphreybcquickshot isn't really a screenshotting application - that's what it does, yes, but it's only a small part. the big part of quickshot is that it sets up a new default user with the default theme, switches users to that user, pulls a branch full of some code that tells it what screenshots need to be taken. Quickshot then tells the user what screenshot they'll be taking, tells them to set up their screen, takes the shot and 04:26
humphreybcthe UI looks like this at the moment: [SLIDE 8]04:26
humphreybcFor the technical peeps: it's written in Python using Quickly and Glade to design the UI04:27
humphreybc[SLIDE 9]04:27
humphreybcOkay, so, how you can help us!04:27
humphreybcWhat's cool about our project is:04:27
humphreybc1. We cover a huge range of stuff, from programming to writing, to editing and artwork, to maintaining social sites and updating twitter. you name it, we do it.04:28
humphreybc2. We are fast paced, we're fun to work with, and there are always things happening04:28
humphreybc3. We run a lot of events and we do a lot of cool stuff04:28
humphreybcand 4. We make it easy for you to join and get started04:29
humphreybcSo, questions?04:29
humphreybcno one has any questions at all?04:30
humphreybcyay!04:30
ClassBotvdquynh asked: Is Quickshot ready to be used right now?04:30
humphreybcNope, it's not. It's still under heavy development - I only thought of the idea last week :P04:30
humphreybcyou can check out the branch though, http://launchpad.net/quickshot04:30
humphreybcbzr branch lp:quickshot04:30
humphreybcyou can run it by double clicking the run.sh script04:31
humphreybcTommyBrunn is working on the Python with ubuntujenkins, i'm helping with the UI and bzr stuff04:31
humphreybcand yes, we do need help!04:31
humphreybcthat's okay04:32
humphreybcwhen it's finished it will be super dooper easy to use :P04:32
humphreybcabeisgreat, meh, i'm not very good at python either04:32
humphreybcany help would be useful, honestly04:32
ClassBotepkugelmass_lern asked: How are discussions progressing with the Ubuntu distro drivers? Are they actively considering Ubuntu Manual for 10.04 release? I know the feature freeze (a3) is coming up fast.04:33
humphreybcNo, they're not. It won't be in the Lucid CD because a) Lucid is an LTS b) we're a very young project and c) we weren't at UDS-L to actually suggest it04:33
humphreybcbut don't worry, it will be easily accessible on websites/repos etc04:33
humphreybcand i'll put it forward for 10.10 :)04:33
humphreybcshould be on the CD for 10.1004:33
ClassBotTakyoji asked: Where would it be listing of what exact screenshots need to be taken? Also, is it on a basis of a person being assigned to taking screenshots of the same dialog in different languages, or?04:34
humphreybcWhat's happening is the authors are inserting a command into their latex chapters where they think a screenshot is necessary. in the compiled PDF it looks like "MISSING SCREENSHOT" and has a description underneath04:34
humphreybcthese missing screenshots are actually exported to a file in the branch "screenshots.log" i think04:34
humphreybcthat list will be taken, with some nifty scripting, and duplicated for 40 different branches, one for each language04:35
humphreybcinside each branch will be folders for chapter, and in each chapter will be the relevant screenshots as plain text files containing their description. Quickshot will be programmed to find plain text files and treat them as "screenshots that are yet to be taken"04:35
humphreybcit will pull the description out, and, when the shot is taken, replace the plain text file with an image file ending in .png04:36
humphreybcQuickshot will then ignore .png files as they've already been done :)04:36
humphreybcWe are aiming to get this thing ready for the Ubuntu Global Jam04:36
humphreybcso we can get tonnes of people screenshotting04:36
humphreybcoh also, Quickshot will have the ability to change the system language for the "quickshot" user04:37
humphreybcobviously all the english screenshots will be captured first04:37
humphreybcso once that's done, we'll have to have the user switch to another language for taking shots :)04:37
humphreybcgood question.04:37
humphreybchttps://wiki.ubuntu.com/ubuntu-manual/quickshot04:38
ClassBotAbeisgreat asked: How far along is quickshot? I know you said it's only a week old, but how far is it?04:39
humphreybcsurprisingly we're doing pretty well04:40
humphreybcI've finished most of the main UI dialogs04:40
humphreybcQuickshot at the moment can:04:40
humphreybcCreate a new user04:40
humphreybcPrompts the current user to switch (and has a button to do that)04:40
humphreybcopens on start in the quickshot user04:40
humphreybcaccount04:40
humphreybcit can also remove that user04:40
humphreybcnext on the list is creating the bzr branch, pulling it and installing dependencies like language packs and fonts if they want to change language04:41
humphreybcwe're aiming for it to be ready by March 18th (manual beta, lucid beta)04:41
humphreybcand then finished bug-free by April 1st04:41
humphreybcThat gives us about a month of solid screenshotting till our RC on the 20th of April04:41
humphreybcwe'll start the english screenshots on March 4th which is the Lucid UI freeze04:42
humphreybcand we are going to use those as "example" shots04:42
humphreybcit's all very busy04:42
humphreybcyep, it's a cool project04:43
humphreybcI really like quickshot, it's a bit of fun04:43
ClassBotTakyoji asked: What if the default theme in Lucid is changed?04:43
humphreybcthe default theme is changing in Lucid :)04:43
humphreybcwe're packaging Quickshot actually for Lucid, and targeting it at Lucid testers04:44
humphreybcand after March 4th, Lucid won't and can't change in appearance at all because that's the User Interface freeze04:44
humphreybcwe don't have much time, so we'll need all the help we can get04:44
humphreybcand we're designing quickshot to be as easy and automated as humanly possible04:44
humphreybcso even your grandma should be able to capture screenshots for us!04:44
ClassBotvdquynh asked: How will we interact with bzr? Will it be sufficient to have a Launchpad account?04:45
humphreybcYes, the branch will be entirely open so anyone with an lp account should have write permissions and auto-merging. We are considering seeing if the launchpad guys can actually make our branch public so _anyone_ (even without an lp account) can push. Either that, or ask them to sign in on Quickshot and if they don't have an account, create one through Quickshot04:46
ClassBotTakyoji asked: Would that imply that March 4th would be a reasonable time to start helping with taking screenshots? (or whenever the new theme is officially released)04:46
humphreybcNot much will be happening around March 4th, but on March 18th there will be a huge rush as all hands man the screenshot pumps!04:46
humphreybcWe're aiming to get everything out of the way in the project before march 18th - that means writing, content, editing, icons, title page, artwork, style, colours... everything04:47
humphreybcMarch 18th is our writing freeze so translations can catch up04:47
humphreybcso all of our team will be screenshotting for a whole month04:47
humphreybc:)04:47
ClassBotvdquynh asked: Do I understand well that translations shoud better start after March 18th?04:48
humphreybcyep, at the moment translations are a bit hay-wire. I wasn't even planning on having anything more than an english manual, so I never thought about translations. Then all of a sudden we had like 100 people from all countries start emailing us asking for translation support, so we rushed to build it in04:49
humphreybcthe problem with translating stuff early is that it is subject to change04:49
humphreybcand so a lot of the stuff they're translating is changing every day as authors and editors re-work sections and bits and pieces04:49
humphreybcI would wait until March 18th to start translating, because then you know anything you do will stick as our writing is frozen. Anything in the manual on March 18th is there for good, no exceptions. (unless some cheeky blighter drops in a swear word somewhere right before the freeze)04:50
humphreybcyup :)04:51
humphreybcmore questions? we've still got 10 minutes until i start rambling on about ground control and how cool it is :)04:51
humphreybccool :)04:53
humphreybchttp://launchpad.net/groundcontrol04:55
ClassBotTakyoji asked: What will be the licensing of the Ubuntu Manual?04:59
humphreybcCreative Commons Attribution Share Alike :)04:59
=== ChanServ changed the topic of #ubuntu-classroom to: Welcome to the Ubuntu Classroom - http://wiki.ubuntu.com/Classroom || Support in #ubuntu || Upcoming Schedule: http://is.gd/8rtIi || Event: 48 Hours of Ubuntu Manual Learning - Current Session: Using Ground Control to make changes - Instructor: humphreybc || Questions in #ubuntu-classroom-chat
humphreybcwhich basically means that it's free, anyone can use the source code, copy it, change it, redistribute it etc05:00
humphreybcokay, ground control!05:00
humphreybc[SLIDE 1]05:00
humphreybconce again, slides available @ http://kevin.godby.org/ubuntu-manual/talks/05:00
humphreybcor if you're using Lernid, you should see them to the top right!05:01
humphreybcSo, Ground Control is basically a front end to bzr/bazaar05:01
humphreybcit's a python plugin for Nautilus written by Martin Owens05:01
humphreybcit's pretty sweet, avoids the command line entirely and makes stuff a lot simpler05:01
humphreybcit's not perfect yet, but it does the job and martin needs more testers so I offered to use it in UMP05:01
humphreybcsoooo for you to install it and run it, i've made a handy dandy walkthrough video05:02
* humphreybc tries to find the link05:02
humphreybchttp://www.youtube.com/watch?v=MeNXqfofbWk05:02
humphreybcit should appear in Lernid05:02
humphreybcso have a watch of that05:03
humphreybcit's just over 6 minutes long05:03
humphreybcand let me know when you've watched it :)05:03
humphreybc[SLIDE 2]05:05
humphreybcI just put the commands in the slideshow window05:05
humphreybcokay so everyone watched it?05:08
humphreybcplease say something so i know there are still people here...05:08
humphreybcokay cool we can wait, we've got tonnes of time05:08
humphreybcgroovy, ok we'll move on but i'll leave the video there05:09
humphreybc[SLIDE 3]05:10
humphreybcso basically, as you can see from the video it's pretty easy to use05:10
humphreybcwhere some people had difficulty earlier today was with setting up the SSH key when logging into your account05:10
humphreybcso let me know if that's a problem for anyone05:10
humphreybcbasically just the most important thing is to a) make sure you're a member of our team05:11
humphreybcand b) check the "download my branch" radio button05:11
humphreybcif you choose either of the other two, you'll end up with a read only branch that you can't commit, or you'll push and create a merge proposal. We avoid merge proposals, and i'll tell you why05:11
humphreybcother projects that are crucial to the system, such as the boot team stuff, software center, synaptic etc05:12
humphreybcthey use merges because they don't want someone coming along and deleting all the code or stuffing it up and then pushing to main05:12
humphreybcso they review each merge and approve or decline it for inclusion into main05:12
humphreybcwhy don't we do that? easy:05:12
humphreybc1. We have so many people committing and making revisions, we'd have merge proposals coming out of our easr05:13
humphreybcears*05:13
humphreybc2. We don't have time to bother with merge reviews because we're too busy working on the project - we have a tight enough schedule as it is without a full time merge reviewer!05:13
humphreybcBut you may say "well what happens if someone breaks something?" - we can easily revert to an earlier revision05:13
humphreybcin this case, not having merges has more benefits for us than cons05:14
humphreybcso, that's why you "download my branch" so you can push directly into main05:14
humphreybcremember the requirements to be able to get our branch. You need:05:14
humphreybc1. A launchpad account05:14
humphreybc2. An SSH key for your computer05:14
humphreybc3. To be a member of our team05:14
humphreybc4. Have bzr or Ground Control installed05:14
humphreybc[SLIDE  4]05:15
humphreybc[SLIDE 5]05:15
humphreybcwait05:15
humphreybc[SLIDE 4]05:15
humphreybcthere we go :P05:15
humphreybcOkay so you probably don't need to know this but I think it's quite cool so i'm going to tell you05:15
humphreybcat the end of the video you might have noticed some buttons that say "Make Show" and "Make Clean"05:15
humphreybcvdquynh: good question, i'll have to find out. hang on, i'll answer that in a sec :)05:16
humphreybcokay so these developer buttons are a feature in Ground Control 1.505:16
humphreybcbasically in the root of our branch there is a file called .gcfunctions05:17
humphreybcHow do we know if our computer has a ssh key? and how to find it?05:17
humphreybcoops05:17
humphreybchttp://www.youtube.com/watch?v=MeNXqfofbWk05:17
humphreybccopy pasta fail05:17
humphreybcso where was I? ah, right, .gcfunctions05:18
humphreybcin this file there is some basic code that sets up some buttons with a label and a command05:18
humphreybcall they run is "make show" and make clean05:18
humphreybci just thought they were neat :)05:18
humphreybcokay, your question05:18
ClassBotvdquynh asked: How do we know if our computer has a ssh key? and how to find it?05:18
humphreybcI *think* Applications > Accessories > Passwords and Encryption Keys. "My Personal Keys" tab, and there should be a key for SSH05:19
humphreybcalso, on launchpad, go to your profile (ie, mine is https://launchpad.net/~humphreybc )05:19
humphreybcand it should say you have an SSH key05:19
humphreybcsee how it says "SSH keys: benjamin@benjamin-laptop" ?05:20
humphreybchttps://help.launchpad.net/YourAccount/CreatingAnSSHKeyPair05:21
humphreybcvdquynh: have a look at that05:21
humphreybcit runs you through setting up an SSH key05:21
humphreybcsweet :)05:22
humphreybcso any other questions about ground control or bzr?05:22
humphreybcThere is a session later on on launchpad where i explain more about launchpad features05:22
humphreybcthe logs for all of these sessions can be found on http://irclogs.ubuntu.com05:22
humphreybcand the slides are on godbyk's website, also in our bzr branch under the folder "48hours"05:23
humphreybctomorrow that folder will be renamed to "help"05:23
humphreybcto get the branch, follow the ground control video, or run "bzr branch lp:ubuntu-manual" in a terminal05:23
humphreybcany other questions?05:24
* humphreybc likes it how he has a 2 hour break to get some dinner before talking about social media05:24
humphreybc neat! well stick around because josh and Ilya have some really cool presentations coming up05:25
humphreybc(If you're using Lernid, you can check out the schedule by clicking on "Schedule" up the top) - it also gives you the times in your local timezone!05:26
humphreybcokay fellas, i'm off to grab something to eat :)05:27
humphreybcany questions you have, just ask in #ubuntu-manual on irc.freenode.net05:27
humphreybcJosh will start his session on translations in about 30 minutes05:27
=== nhandler_ is now known as nhandler
humphreybchave fun dutchie!05:52
=== ChanServ changed the topic of #ubuntu-classroom to: Welcome to the Ubuntu Classroom - http://wiki.ubuntu.com/Classroom || Support in #ubuntu || Upcoming Schedule: http://is.gd/8rtIi || Event: 48 Hours of Ubuntu Manual Learning - Current Session: Translations and how they work - Instructor: dutchie || Questions in #ubuntu-classroom-chat
dutchieOK, here we go again ;)06:00
dutchieHi everyone, and welcome to my talk on the translations system used by the Ubuntu Manual project.06:00
dutchieMy name is Josh Holland, and I go by the nick dutchie.06:00
dutchieI've been involved in the Ubuntu Manual project since pretty much the beginning.06:00
dutchieI run a fair bit of the backend stuff, including the IRC bot, the planet, and, of course, the translations.06:00
dutchieWhat I'm going to cover today includes:06:01
dutchie* How to contribute a translation06:01
dutchie* A brief overview of the translation infrastructure06:01
dutchie* How to build a translated version of the manual06:01
dutchieIf you've got a question, stick it in #ubuntu-classroom-chat with QUESTION: at the front and I'll answer it when appropriate.06:01
dutchieI'll also pause for questions at the end of each section.06:01
dutchieSo, let's get started!06:01
dutchie(It's 6 AM here, so if I stop making sense, tell me ;) )06:01
dutchie[How to contribute a translation]06:02
dutchie(ooh, sorry - no slides for me. Ones on translation won't really be that interesting, and you've got the links to look at)06:03
dutchieThis is easy! Just go to http://translations.launchpad.net/ubuntu-manual and click on the language you want to translate.06:03
dutchieYou will then see the Launchpad translations UI.06:03
dutchieAll you have to do now is enter your translations into the boxes06:03
dutchieThey will then be reviewed, and hopefully included in the final translation!06:04
dutchieAny questions so far?06:04
dutchie[The translation infrastructure]06:06
dutchieThe Ubuntu Manual and Launchpad use the GNU Gettext system of translations06:06
dutchieThis is centred around two types of file: .pot files and .po files.06:06
dutchie.pot files are translation template files, and contain all of the strings that need translation06:06
dutchieOurs is called ubuntu-manual.pot, and, along with all the .po files, lives in the po/ directory at the top of the source tree06:07
dutchieYou can see all of the translation files here: http://bazaar.launchpad.net/~ubuntu-manual/ubuntu-manual/main/files/head:/po/06:07
dutchieThe .po files are the ones which actually contain the translations06:07
dutchieThey are named after the language they translate, such as fr.po for the French translation, and en_GB.po for the British English one06:07
dutchieMore information about the format of .pot, .po and .mo (which we don't need) files is available from http://www.gnu.org/software/gettext/gettext.html06:08
dutchieEssentially, a .po file contains a list of untranslated strings and translated strings next to each other, in a well-defined parsable format06:08
dutchieThe text is indexed by file and line number to make it easy to match up where it came from06:09
dutchieGNU Gettext is mainly intended to translate software programs, rather than documentation06:09
dutchieWe therefore can't use it directly, becuase it is normally used as a software library06:09
dutchieSo, to translate a Python program for example, you'd do "import gettext", then pass every string that needs translating to a special function06:10
dutchieOther languages supported by gettext (all major ones) work in much the same way06:10
dutchieInstead, we use po4a, or po for anything (http://po4a.alioth.debian.org)06:10
dutchieThis is a set of Perl scripts that allow you to use the infrastructure built up around translating Gettext files for your project06:10
dutchieThere is a lot of infrastructure based on .po and .pot files06:11
dutchieRosetta (Launchpad's translation interface) is an excellent example, but there are other po editors, such as po mode in Emacs, and GUI ones like poedit06:12
dutchieIt supports manpages, Perl pod format, xml, sgml, TeX, plain text, ini and KernelHelp files06:12
dutchieIt can be run using individual commands analogous to msgmerge, xgettext and friends, but it is easier to use the po4a(1) command and a configuration file06:12
dutchieWe only need the TeX support, but as you can see, it can be used in a wide range of situations06:13
dutchieAny questions on Gettext or po4a?06:13
dutchiehmm06:15
dutchieClassBot: wake up06:15
dutchie < vdquynh> Question: I either translate directly in LP or I download the vi.po file to work with poedit. IS that OK or should I use po4a when offline?06:15
dutchieYou, as a translator, will never need to worry about po4a06:16
dutchieThat's a tool I use to generate and keep the po files up to date06:16
dutchieWe'd prefer it if you worked directly on Lauchpad06:16
dutchieYou'll see why in a moment when I go through updating the translations06:17
dutchieBut, if you like, you can use poedit on the files in the bzr tree and commit and push like that06:17
dutchieNo more questions?06:17
dutchie[How the translations are updated]06:18
dutchieI try to update the translations around every day.06:18
dutchieHowever, I have a busy life and I don't always manage this, so be gentle if I forget ;)06:18
dutchieThere are two stages to updating the translations.06:18
dutchie1. Updating the translated files06:18
dutchie(Pulling in the new translations from Launchpad)06:19
dutchie2. Updating the translation .pot file06:19
dutchie(Changing the .pot file, and possibly the .po files, if any of the content has changed)06:19
dutchieThe translations done on Launchpad are exported into the lp:~jshholland/ubuntu-manual/manual-trans branch06:19
dutchie(This is very clever and useful, a very handy Launchpad feature)06:20
dutchieI merge this in, which inevitably results in conflicts. These are resolved by just using the copy from LP, and discarding any local changes.06:20
dutchieThis is the bit that gives Launchpad translations the "upper hand"06:20
dutchieIf someone translates the same bit on Launchpad as someone else in the bzr branch, the Launchpad version will be used06:21
dutchieHowever, if it's unchanged, it will be picked up when Launchpad scans the branch (another awesomely cool feature)06:21
dutchieOnce I've done this, I commit the merge and run the following command:06:22
dutchie$ po4a --no-translations --copyright-holder="The Ubuntu Manual Team" --package-name=ubuntu-manual --package-version=$(bzr version-info --custom --template={revno}) po4a.conf06:22
dutchie(it's a big one :) )06:22
dutchieThis command updates the .pot file and .po files, without generating translated content, and sets appropriate values in the files.06:22
dutchieAs I said, I'm the only one who needs to worry about po4a06:23
dutchieBut, if you're interested, the po4a.conf control file is visible here: http://bazaar.launchpad.net/~ubuntu-manual/ubuntu-manual/main/annotate/head:/po4a.conf06:23
dutchieIt's very small06:24
dutchiepo4a works a lot of the details out for itself, which is quite handy06:24
dutchieThis is then committed and the whole lot is pushed up to Launchpad.06:24
dutchieLaunchpad then scans the branch, and imports the .po and .pot files to use as a basis for the translations done.06:24
dutchieThis means that any new translations done in the branch are imported back into Launchpad06:25
dutchie(if they haven't been overwritten)06:25
dutchieThe cycle then repeats.06:25
dutchieAny questions about how this all works?06:25
ClassBotvdquynh asked: how much time between the start and end of process for any language?06:26
dutchieHard to say really06:26
dutchieAll of the languages have been open the same time06:27
dutchieI'm sure that they've all got a different number of translators working on them06:27
dutchieAs of now, the translation into British English (yes, that has to be done) is complete06:27
dutchieThe rest are all at varying stages of completion, as you can see by going to http://translations.launchpad.net/ubuntu-manual and clicking "Show all languages"06:28
dutchieThat leads fairly nicely on to freezes06:29
dutchieAt the beginning, we had lots of content being written and edited06:29
dutchiePeople would translate something, then a day or two later, the original would change, and it'd have to be translated again06:30
dutchieThis was quite a problem up to the alpha06:30
dutchieNow, though, less of the content is being changed, but this problem hasn't gone away completely06:31
dutchieSo, at the beta, we intend to freeze all writing and editing06:31
dutchieThis would give the translators a chance to catch up with all of the content before final release06:31
dutchieQuestions on the freeze?06:32
ClassBotvdquynh asked: When an original string has been translated and changes, is the translated string automatically dismissed or flagged in some way that the translator knows that he /she has to do it again?06:32
dutchiepo4a detects that the string has changed and updates the .pot and .po files06:33
dutchieThis means that the string has to be translated again06:33
dutchiepo4a keeps track of that sort of thing internally06:34
dutchieJust to make this clear, you can do translations now, but there is a small chance they will be lost if the original string changes06:34
dutchieKeep working from now until your language is done, then learn another language and do that one ;)06:35
dutchie[How to build a translated version of the manual]06:35
dutchieThis bit was written when you didn't require Tex Live 2009 anyway06:36
dutchieso ignore it for now :)06:36
dutchieThanks to some cool work from godbyk, our LaTeX guru, it's not too hard to see your translations in the manual.06:36
dutchieUnfortunately, we've had to use the polyglossia LaTeX package to handle the translations.06:36
dutchieThis is only available with texlive 2009, which is only in the repos for Lucid (10.04).06:36
dutchieSo, if you're running Karmic (9.10), you have two choices:06:36
dutchie1. Upgrade to Lucid06:36
dutchie2. Download and install texlive 2009 directly from upstream06:36
dutchieThis set of instructions was taken from https://lists.launchpad.net/ubuntu-manual/msg00548.html (thanks godbyk)06:36
dutchieThe first part of this will only apply to people running Karmic (or earlier).06:36
dutchieStep one is removing any texlive packages you've already got.06:36
dutchieYou can do this on the command line via "sudo apt-get remove texlive-*" or through Synaptic.06:36
dutchieThe next step is to download http://mirror.ctan.org/systems/texlive/tlnet/install-tl-unx.tar.gz, the install script for texlive06:37
dutchieYou can then unpack the tarball by "tar -xvvzf install-tl-unx.tar.gz" and change into the newly unpacked directory06:37
dutchieOnce in there, run "sudo ./install-tl". The defaults it selects are normally quite good, but you can remove the documentation packages for a smaller download (the full one is about 2.5G!)06:37
dutchieThis will take quite a while, so be patient.06:37
dutchieOnce this is done, change into the ubuntu-manual directory, and run pkgs/install-pkgs.sh script06:37
dutchieThat's the Karmic-specific stuff out of the way. Lucid folks can just install texlive-base.06:37
dutchieIt should hopefully find everything; if it doesn't, and you're on Lucid, it's safe to install the suggested ones06:37
dutchieIf you're on Karmic, however, something has gone wrong with the installation.06:37
dutchieDrop into #ubuntu-manual and we'll try and help you out.06:37
dutchieSo now you've got all the texlive 2009 packages installed, you can build the manual.06:37
dutchieOK, you can start listening again06:37
dutchieThis is really easy once you've got everything installed06:37
dutchieThis is easy: just type "make ubuntu-manual-LANG.pdf", where LANG is the language code (corresponding to one of the .po files in po/) you'd like to build.06:37
dutchie(so, to build the French version, "make ubuntu-manual-fr.pdf")06:38
dutchieAll being well, the manual will now build, and you can see the fruits of your labour06:38
dutchieYou may need to install some font packages. The ones you need will be in the error message from LaTeX, and can be found in a package starting with ttf-06:38
dutchieIf you're having problems, ask godbyk. He should know what you need to do06:38
dutchieAny questions on that?06:38
dutchieThat's pretty much all I have to say about translations.06:40
dutchieI hope this has helped you to understand how the translations, and maybe do some translations for yourself!06:40
dutchieThanks a lot for coming along.06:40
dutchieI've now got 20 minutes to answer any questions you've got left06:40
dutchieI was obviously very comprehensive :)06:50
dutchieOK, thanks everyone for coming06:58
dutchieNext is IlyaHaykinson_ with a talk on Writing Style06:58
=== ChanServ changed the topic of #ubuntu-classroom to: Welcome to the Ubuntu Classroom - http://wiki.ubuntu.com/Classroom || Support in #ubuntu || Upcoming Schedule: http://is.gd/8rtIi || Event: 48 Hours of Ubuntu Manual Learning - Current Session: Writing style - Instructor: IlyaHaykinson || Questions in #ubuntu-classroom-chat
IlyaHaykinsonhm, we need to give voice to ClassBot07:01
IlyaHaykinsonok, folks, we'll start in 2 mins07:02
IlyaHaykinson[SLIDE 1]07:02
IlyaHaykinsonYou can also see the slides at http://www.slideshare.net/ilyah/writing-the-ubuntu-manual07:03
IlyaHaykinsonAlright. Welcome, folks.07:06
IlyaHaykinsonAgenda: [SLIDE 2]07:06
IlyaHaykinsonIn this talk, we'll chat about how difficult it is actually to write a good manual07:06
IlyaHaykinsonWe'll consider what kind of an audience we're writing for, and what that means to us when writing it.07:07
IlyaHaykinsonWe'll discuss what our combined voice should be -- how should we relate to the reader?07:07
IlyaHaykinsonAnd we'll briefly chat about some desktop conventions that you should use when writing.07:07
IlyaHaykinsonPlease feel free to ask questions, but I'll try to take them all at once in the breaks between sections.07:07
IlyaHaykinsonWriting a Manual: Challenges -- [SLIDE 3]07:08
IlyaHaykinsonThere's a lot to be decided when writing a manual for an open project of the size of Ubuntu07:08
IlyaHaykinsonwe need to figure out what we include -- and, more importantly, what we leave out.07:08
IlyaHaykinsonwe've got to decide on grammar -- British? United States? International? what about non-English?07:08
IlyaHaykinsonwe need to decide on the voice -- should we be humorous? serious? playful?07:09
IlyaHaykinsonwe need to understand the audience that we hope will read the manual, and use that information to decide how to present the information.07:09
IlyaHaykinsonfinally, some pratical limitations come up -- we cannot include 1000 screenshots (the file size will be too large, it will take too long to take screenshots, etc)07:09
IlyaHaykinsonso, we compromise on all of these points.07:10
IlyaHaykinsonfor Content, we decided to cover only the core of the Ubuntu Desktop.07:10
IlyaHaykinsonfor Style, we picked a relatively serious tone, and a grammar that is similar to the Ubuntu Docs team07:10
IlyaHaykinsonfor our Audience, we decided to go after new computer users and people new to Ubuntu -- this meant that we did not dive very deep, but provided enough information to let people accomplish some key tasks in the simplest way.07:10
IlyaHaykinsonand, again, practical limitations guide us throughout.07:10
IlyaHaykinsonWriting Challenges: Other Sources -- [SLIDE 4]07:11
IlyaHaykinsonWhen writing a manual, we need to understand that almost everything that we write about has already been covered by documentation.07:11
IlyaHaykinsonSome of it is Ubuntu's own, some of it comes from the community.07:11
IlyaHaykinsonTo the degree that we can, we need to both read and then if possible _copy_ the documentation.07:11
IlyaHaykinsonThis copying is limited by fit -- some of the documentation will not work for us when copied.07:11
IlyaHaykinsonFor example, Ubuntu's documentation is mainly oriented at specific tasks -- it rarely provides a high level overview to help a user get started and get the larger picture07:12
IlyaHaykinsoninstead it dives directly into specific pages and screens to help answer one particular question.07:12
IlyaHaykinsonWe can certainly use it to understand how something works, and can copy parts of it, but we cannot copy it in entirety -- it would not match our style or voice07:12
IlyaHaykinsonThe GNOME project also has a lot of documentation. Their docs are actually well-created -- well written, organized in a logical way, etc.07:12
IlyaHaykinsonHowever, GNOME licenses using the GNU Free Documentation License, which is not compatible with the Creative Commons - Attribution - ShareAlike license that we are using.07:13
IlyaHaykinsonThus, we can read the GNOME docs, but not use them directly in the manual.07:13
IlyaHaykinsonFinally, there's community documentation. Such great things like the ubuntuguide.org or any other fan pages07:13
IlyaHaykinsonor user guides07:13
IlyaHaykinsonMost of these are great, but most of these are also not perfect since they target experts, and not beginners07:13
IlyaHaykinsonWe can read them and use them in our troubleshooting sections, but not really much else.07:14
IlyaHaykinsonAny questions before I move on?07:14
IlyaHaykinsonok, moving on to Our Audience07:14
IlyaHaykinsonNext slide - Our Audience: New Users -- [SLIDE 5]07:14
IlyaHaykinsonWe've decided to focus our writing on people who are new to Ubuntu07:15
IlyaHaykinsonthis may also mean that they're new to computers in general07:15
IlyaHaykinsoneither actually new users, or just very much beginners in their skill set07:15
IlyaHaykinsonFor our writing, we assume that the reader knows how to use a GUI -- they know how to use the mouse, or the keyboard07:15
IlyaHaykinsonthey also know that there are windows and buttons and scrollbars, and generally know how to use them to get around.07:15
IlyaHaykinsonThey may not know that their monitor is a monitor -- lots of people call their monitor their "computer"07:16
IlyaHaykinsoni've even seen people call the actual desktop the "brain"07:16
IlyaHaykinsonthey will not know what ethernet is, necessarily; we need to remind them about wifi.07:16
IlyaHaykinsonthey will certainly not know anything more complex than that.07:16
IlyaHaykinsonNext slide - Our Audience: New Users -- [SLIDE 6]07:16
IlyaHaykinsonSo, we need to be very careful when writing to not include any jargon in our presentation.07:16
IlyaHaykinsonWe need to explain, in detail, everything that we mention.07:17
IlyaHaykinsonwe can say "click the ____ button", assuming that the person will see the button07:17
IlyaHaykinsonand knows how to click07:17
IlyaHaykinsonbut, for example, we need to say "Click-and-hold your mouse button at the edge of the window, and drag your mouse to resize the window"07:17
IlyaHaykinsoninstead of assuming the person knows what to do.07:17
IlyaHaykinsonwe need to define all terms; in a section on printing, we may want to say "Your printer may connect to your computer using a USB cable. Before starting, plug your printer into an available USB slot on your computer."07:17
IlyaHaykinsonbecause a user may not remember on their own07:18
IlyaHaykinsonWe need to be very precise in our language -- need to know the terms for everything in the operating system.07:18
IlyaHaykinsonso that when we refer to a piece of the user interface, we are consistent with other documentation07:18
IlyaHaykinsonand consistent with ourselves07:18
IlyaHaykinsonI will cover some terms later, but there's a great guide for GNOME user interface terms at http://library.gnome.org/devel/gdp-style-guide/stable/gnome-glossary-desktop.html.en07:18
IlyaHaykinsonMost importantly, when writing for new users, we need to start with very simple things. We can move on to more advanced topics only after we've repeated the simple things again, and again, and again.07:19
IlyaHaykinsonFor example, we may start with talking about "Click-and-hold ... to resize" at first.07:19
IlyaHaykinsonAnd by the end of a section, just say "resize" since we can assume the user has learned a bit already.07:19
IlyaHaykinsonNext slide - Our Audience: Eager to Learn -- [SLIDE 7]07:19
IlyaHaykinsonWe are writing for people who picked up a manual.07:19
IlyaHaykinsonPeople who have either already installed, or interested in installing Ubuntu -- which is saying that they're a captured audience, in a way.07:20
IlyaHaykinsonThey are somewhat task oriented in their day to day computing life -- they have no interest in learning the underlying ways things work in Linux or Ubuntu07:20
IlyaHaykinsonany more than they want to know how the Win32 API works, or that MacOS is based on Darwin.07:20
IlyaHaykinsonbut they _do_ care to know how to make their printer print. or their scanner scan. or their presentation saved as PDF.07:20
IlyaHaykinsonbecause those are actually their goals.07:21
IlyaHaykinsonSince we are writing a manual, they may read the manual in fairly large chunks -- many pages at once -- instead of just as a reference guide where they use the index, jump to a page, read a tiny bit, and close it.07:21
IlyaHaykinsonNext slide - Our Audience: Eager to Learn -- [SLIDE 8]07:21
IlyaHaykinsonSo, the recommendations are aligned with this eagerness to learn07:21
IlyaHaykinsonwe need to keep a narrative that turns a novice into a knowledgeable user over time.07:21
IlyaHaykinsonAs i mentioned, start simple -- progress to complex07:22
IlyaHaykinsonWe need to think in terms of these user tasks -- title each section with a particular task, and cover only that one task.07:22
IlyaHaykinsonDon't just write how to do something -- make sure you have some indication _why_ someone would want to do something07:22
IlyaHaykinsonUse asides, callouts, and notes in the margins to keep the advanced users happy, too (godbyk's talk on LaTeX will explain how to do this, technically, in the manual)07:22
IlyaHaykinsonso if there's something that you think they _might_ want to know, after reading your manual, stick it in a margin note.07:23
IlyaHaykinsonand if it's advanced, and they probably do not _need_ to know it, mark it as advanced.07:23
IlyaHaykinsonFinally, do not patronize -- do not be condescending to the user.07:23
IlyaHaykinsonThe user wants to get some work done.07:23
IlyaHaykinsonthey do not need to be told something is "simple"07:23
IlyaHaykinsonit may not be simple for them, and  they'll assume you (the writer) is better than them07:24
IlyaHaykinsonand is taunting them with your betterness07:24
IlyaHaykinsondon't tell them to "just click on" something -- they may take a minute to find that something, and again will feel like you're saying their dumb if it took them a while to find it.07:24
IlyaHaykinsonin general, assume that you're giving a list of instructions on how to reach a particular physical address.07:24
IlyaHaykinsonyou tell people "off the highway, third light, make a right; past the gas station, make a left. then, it's the second building on your right"07:25
IlyaHaykinsonthat same fairly serious tone should be kept when talking to the user.07:25
IlyaHaykinsonNext slide: Our Audience: International -- [SLIDE 9]07:25
IlyaHaykinsonWe are writing in English. But we've got a lot of translations (40+). Plus, even for people reading in English, some may not have it their native language07:25
IlyaHaykinsonPlus, not all humor or witty comments are universal.07:25
IlyaHaykinsonNext slide: Our Audience: International -- [SLIDE 10]07:26
IlyaHaykinsonSo, we need to use _very_ simple language.07:26
IlyaHaykinsonAlways use a simpler synonym for a word.07:26
IlyaHaykinsonNot "transform" but 'change'. Not "alphabetize" but "put in alphabetical order"07:26
IlyaHaykinsonUse simple phrases as much as possible. Shorter sentences are better.07:26
IlyaHaykinsonIf you have lots of words in dependent clauses etc, it will make it hard to translate and understand.07:27
IlyaHaykinsonSo use a period instead of a semicolon. List out steps in an enumerated list (1. click here. 2. click there. 3. enter some text. etc)07:27
IlyaHaykinsonAssume that you are speaking to an advanced English learner, basically.07:28
IlyaHaykinsonAs a design decision, we're using American spelling and grammar for the manual. This is consistent with the Ubuntu documentation team and other Ubuntu/Canonical guidelines.07:28
IlyaHaykinsonAlso, use short paragraphs. If a paragraph has more than 5 sentences, it's probably too long.07:28
IlyaHaykinsonRepeat yourself. So "You may want to use a calculator to help with a calculation. To use a calculator in Ubuntu, click ..."07:29
IlyaHaykinsonSaying this in two phrases helps solidify the concept, and prevents ambiguity.07:29
IlyaHaykinsonAny questions before moving on to Our Voice?07:29
IlyaHaykinsonNext slide: Our Voice: Confident -- [SLIDE 11]07:29
IlyaHaykinsonWe are writing a manual, and we are the experts. Our readers are expecting us to be condident in our opinions.07:30
IlyaHaykinsonso, when writing, use language that says that you are condident in what you are saying.07:30
IlyaHaykinsonWhen giving opinions, state them as facts.07:30
IlyaHaykinson"With Ubuntu, you can print, scan and email documents"07:30
IlyaHaykinsonno need to say "With Ubuntu, you might be able to ... if you have an internet connection and your drivers work"07:31
IlyaHaykinsonHowever, I suggest that you consider Ubuntu to not be perfect.07:32
IlyaHaykinsonwhen talking about windows opening, when giving instructions, I generally prefer saying "Ubuntu should open..." instead of "Ubuntu will open..."07:32
IlyaHaykinsonThis way, if something doesn't work quite correctly, we are not lying.07:32
IlyaHaykinsonMy personal guideline is that if something is certain to work, use "will". If there's a chance for failure (user clicks in the wrong place, or has a different configuration) use "should"07:32
IlyaHaykinsonNext slide: Our Voice: Direct and Calm -- [SLIDE 12]07:33
IlyaHaykinsonWrite as if you're conversing with a reader, face to face. "You may want to use a calculator. To open the calculator, click..."07:33
IlyaHaykinsonor "If your email administrator advised you to use IMAP..."07:33
IlyaHaykinsonAs part of being calm, avoid generating excitement for Ubuntu.07:33
IlyaHaykinsonwe are writing a manual, not a marketing slick -- no need to use words like "best", "easiest", "simplest", "amazing" etc07:34
IlyaHaykinsoninstead of "In ubuntu, it's easy to do X...." say "In Ubuntu, you can do X by...."07:34
IlyaHaykinsonNext slide: Our Voice: Slightly Opinionated -- [SLIDE 13]07:34
IlyaHaykinsonall that said, we are _SLIGHTLY_ opinionated. Slightly <------ this is an important word07:34
IlyaHaykinsonin the Linux world, there is always more than one way to do things. however, not in our manual.07:34
IlyaHaykinsonin our manual, there are only a few ways.07:35
IlyaHaykinsonFirst, we should recommend the _official_ graphical way to do something.07:35
IlyaHaykinsonSecond, we may recommend any simple variation or common shortcut to doing this.07:35
IlyaHaykinsonBut we stop there. We don't tell people the twenty ways to install software -- just the Software Center and Synaptic.07:35
IlyaHaykinsonThis is because we have a bias towards using the GUI, and being simple.07:35
IlyaHaykinsonWe also try to steer people away from bad decisions, lightly. So "You may want to pick a long password if you are worried about security."07:36
IlyaHaykinsonbut can also allow them the choice to make worse decisions, if there's a good reason. "If you are the only one who will be using your computer, you can decide to automatically log in without entering your password"07:36
IlyaHaykinsonNext slide: Our Voice: Aligned with Users -- [SLIDE 14]07:36
IlyaHaykinsonWhen writing sections, consider how users will want to use what you are describing.07:37
IlyaHaykinsonthen, name the section with a gerund form of a verb.07:37
IlyaHaykinson"Using the calculator" or "Reading your email", or "Scanning images"07:37
IlyaHaykinsonsetting a topic like that also helps make sure you limit the section to just one idea.07:37
IlyaHaykinsonIn each section, mention _why_ a user may want to do that.07:37
IlyaHaykinsonfor example07:37
IlyaHaykinson"If you have a photograph that you want to send over email or post online, you may want to scan it into your computer. To scan images, you will need..."07:37
IlyaHaykinsona quick intro to a section can provide the _why_ a user may want to do something that is vital to establishing context fo rthe user.07:38
IlyaHaykinsonif you just say "to scan images, you will need..." -- you are not letting a user know what possible reason they will ever have that they should read the following paragraph.07:38
IlyaHaykinson<- Any questions before I move on to Conventions?07:38
IlyaHaykinsonNext slide: Conventions: Attribution -- [SLIDE 15]07:39
IlyaHaykinsonWe have a few conventions for the manual. The main one is to write it about Ubuntu, and not about Linux.07:39
IlyaHaykinsonyes, we mention in an early chapter that Ubuntu is based on Linux.07:39
IlyaHaykinsonbut the rest of actions should be attributed to Ubuntu.07:39
IlyaHaykinsonIn general, people will perceive the login process, the desktop, Nautilus, panels, window manager etc as being "Ubuntu"07:40
IlyaHaykinsonutility applications should also be "Ubuntu" for purposes of this manual.07:40
IlyaHaykinsonbigger application packages (Ephiphany, Totem, Open Office) should be considered big enough to warrant their own attribution.07:40
IlyaHaykinsoner, Empathy :)07:40
IlyaHaykinsonso for example, "The Ubuntu calculator lets you...", but "Open Office lets you..."07:40
IlyaHaykinsonAlso, always ensure active voice.07:41
IlyaHaykinsonIf you find yourself writing "It is possible to...", or "...will be opened by..." then chances are you are writing passively07:41
IlyaHaykinsonwhen providing steps to accomplish some task, write imperatively. "Click the OK button", "Choose File, then Save to save a document"07:41
IlyaHaykinsonbut in general, to use an active voice, write "X will do Y" -- "Ubuntu will open a window", "You can click the OK button."07:42
IlyaHaykinsonNext Slide - [SLIDE 16]07:42
IlyaHaykinsonHere we'll briefly run through some common GUI terms.07:42
IlyaHaykinsonbutton and check box -- please note that you click OK, click Cancel, click Forward, but Click _on_ other buttons (Click on Add, click on Remove Entry, etc)07:43
IlyaHaykinsoncheck box is two words, and you either _choose_ and _option_, or _select_ / _deselect_ a check box.07:43
IlyaHaykinsonI prefer "option", when possible.07:44
IlyaHaykinsonNext Slide - [SLIDE 17]07:44
IlyaHaykinsonnothing special here, please just review the list for proper usage07:44
IlyaHaykinsonNext Slide - [SLIDE 18]07:44
IlyaHaykinsonplease note that double-click (and right-click and middle-click and triple-click) use a dash between the words07:45
IlyaHaykinsonand you always double click _on_ something07:45
IlyaHaykinsonyou never drag and drop, but you drag X to Y.07:45
IlyaHaykinsonNext Slide - [SLIDE 19]07:45
IlyaHaykinsonA "field" is a generic term for text boxes, and other input widgets07:46
IlyaHaykinsonfor list boxes, I prefer to _select_ from them, but you can _choose_ as well.07:46
IlyaHaykinsonnote that the top menubar in Ubuntu is called Main Menu07:47
IlyaHaykinsonalso, that a menubar is one word. as is scrollbar, statusbar, titlebar, toolbar07:47
IlyaHaykinsonyou Choose from a menu07:47
IlyaHaykinson[SLIDE 20]07:47
IlyaHaykinsonnote the difference between login and log in -- login is a noun or adjective ("remember your login", "start the login process") but log in is the verb -- "please log in to Ubuntu"07:48
IlyaHaykinsonsame with log out, shut down, etc.07:48
IlyaHaykinsonfor radio button widgets, please use "option"07:48
IlyaHaykinsonLast Slide - [SLIDE 21]07:48
IlyaHaykinsonnote that you click _on_ a tab07:49
IlyaHaykinsonand that you _use_ a text box to _specify_ -- however _enter_ something in the /name/ field is better still07:49
IlyaHaykinson<<-- This concludes my presentation. Any questions?07:49
IlyaHaykinsonPlease see the terms document -- http://library.gnome.org/devel/gdp-style-guide/stable/gnome-glossary-desktop.html.en -- for more info07:50
IlyaHaykinsonOr the list of user actions in GNOME -- http://library.gnome.org/devel/gdp-style-guide/stable/gnome-glossary-user-actions.html.en -- for action names07:50
IlyaHaykinsonFinally, for more tips on writing for an international audience, see http://tc.eserver.org/21590.html07:50
IlyaHaykinsonAlright, thank you for attending! next session in 9 minutes!07:51
=== ChanServ changed the topic of #ubuntu-classroom to: Welcome to the Ubuntu Classroom - http://wiki.ubuntu.com/Classroom || Support in #ubuntu || Upcoming Schedule: http://is.gd/8rtIi || Event: 48 Hours of Ubuntu Manual Learning - Current Session: The project and social media - Instructor: humphreybc || Questions in #ubuntu-classroom-chat
humphreybcso what's the attendance like?08:01
humphreybc(join #ubuntu-classroom-chat to talk)08:01
humphreybcill just wait a couple more minutes so i can finish mt icecream :P08:03
humphreybcwont be long :P08:06
humphreybc[SLIDE 1]08:06
humphreybchttp://www.facebook.com/pages/The-Ubuntu-Manual/266794861575?ref=ts08:06
humphreybchow many people are actually here? could those that are here please say so in #ubuntu-classroom-chat08:08
humphreybcok cool, sorry about the delay ive almost finished my ice cream :D08:09
humphreybcokay so we'll make a start08:11
humphreybcsorry about the delay, i've got my hand back now instead of holding a magnum08:11
humphreybcexcuse me if i don't really know what i'm doing, i've been up since 3am this morning (it's now 9:15pm)08:11
humphreybcalso i don't really have a plan for this session :)08:11
humphreybcokay so08:12
humphreybcsocial media in ubuntu projects08:12
humphreybcusing web 2.0 to our advantage08:12
humphreybcwhy social media is important to us:08:12
humphreybc[SLIDE 2]08:12
humphreybcsocial media increases publicity about a project. this is good because it not only encourages more contributors to help, but it also makes sure more people actually download our end product - which is want we want!08:13
humphreybcmedia attention/blog posts inspire our team to work harder because they feel they are important08:13
humphreybcyou are much more likely to feel good about something if your contributions are rewarded with publicity or commendation08:14
humphreybcand you are much more likely to like to be associated with a project that is visible and popular among the community08:14
humphreybclet me take some examples08:14
humphreybcthe ubuntu manual project, and the boot team working on the new plymouth boot for Lucid08:14
humphreybcthe boot team and plymouth are probably more important, more technical and more interesting than UMP08:15
humphreybcbut we never hear anything about them, apart from the odd update08:15
humphreybcbut then there's UMP, which is younger than the boot team and probably not as important or as interesting or as fundamental to the operation of Ubuntu08:16
humphreybcbut because we have generated a huge amount of hype and publicity, we've had hundreds of contributors come forward willing to help, and we've been able to do 4x as much stuff as I ever envisioned us doing08:16
humphreybcI originally planned this manual to be 50 pages long, a few screenshots, written in open office and only available in english08:17
humphreybcnow we've got this huge project, 250+ contributors, available in 40+ languages, 200 pages long, thousands of localized screenshots and we're even writing our own python program for it!08:17
humphreybcnow none of this would have been possible if it wasn't for the extra contributors we get from:08:17
humphreybcblog posts08:18
humphreybcplanet ubuntu posts08:18
humphreybcfacebook page08:18
humphreybctwitter page08:18
humphreybcidenti.ca page08:18
humphreybcPlanet Ubuntu Manual - http://planet.interesting.co.nz08:18
humphreybcRunning events like this08:18
humphreybcUbuntu Forums survey08:18
humphreybcso, what i'm trying to say, is that with social media, you can create more publicity and attention, with more attention you get more people, with more people you not only get more help but you also get more ideas and feedback - which in turn creates a better overall product.08:19
humphreybcNot enough Ubuntu teams, or open source projects in general, advertise enough.08:19
humphreybcLoco teams should have facebook pages, the Boot team should have facebook pages and regular events to inspire people to help08:19
humphreybcalso, our team works harder because they have an expectation to live up to now08:20
humphreybcif there wasn't hundreds of people commenting on blog posts saying "i can't wait for this manual!" "Ubuntu really needs this!" etc, then we wouldn't be as inspired to do a good job08:20
humphreybc[SLIDE 3]08:20
humphreybcI'll just show  you our facebook/twitter and identi.ca pages real quickly so you can get an idea of how we use them08:21
humphreybcalso, join them! spread them to your friends!08:21
humphreybchttp://www.facebook.com/pages/The-Ubuntu-Manual/266794861575?ref=ts08:21
humphreybcI like facebook the most. Why? Because it's suited to projects! It has the ability to schedule events where people can RSVP to, you can upload photos for people to look at, and you can post twitter style updates to keep everyone informed08:22
humphreybcoh yeah, that's another thing08:22
humphreybctransparency in a project is important08:22
humphreybcwe're lucky in the open source world because everything is transparent anyway, but only if you do some digging08:22
humphreybcyou could quite easily find out what the boot team are up to every day, and what they've done this day etc08:22
humphreybcbut you'd have to do the looking yourself08:23
humphreybcwhy not make it easier by posting updates and keeping the community in the loop of your project?08:23
humphreybcby promoting transparency and keeping everyone informed, we not only hold interest, but we also show that the community and people "outside the team" are valued and important, which they are08:24
humphreybcwe love feedback, we love criticism and I try to make that as clear as possible08:24
humphreybcokay, twitter08:24
humphreybchttp://twitter.com/TheUbuntuManual08:24
humphreybcTwitter is, as most of you know, roughly the same as facebook but without the images and events and extra stuff08:25
humphreybcit's still popular though, of course. we have 119 followers!08:25
humphreybcand we have 177 in facebook!08:25
humphreybcso wait a second, let me get this straight08:25
humphreybcwe're a team of people writing a book for an operating system that has a 1% market share08:25
humphreybcyet we have almost 200 fans on our facebook page?08:25
humphreybcanother thing that projects need to do is run events like this08:26
humphreybcthey achieve a lot of things08:26
humphreybcthey give blogs content and news to write articles on, people read these articles and remember the project08:26
humphreybcthey realise it isn't dead (which happens in the FLOSS world a lot)08:26
humphreybcthese events also attract more contributors08:26
humphreybcand they inform people, they show that we're transparent and we value YOUR opinion08:27
humphreybcwe've set all this up for you to come along and tell us what you think08:27
humphreybcjazz asked: will these lessons or classroom be posted so i can catch  up on what i've missed?08:28
humphreybcyes, they're all available on http://irclogs.ubuntu.com08:28
humphreybcI'll put up the exact logs on the 48 hours wiki page tomorrow :)08:28
humphreybcalso, the slides are available in our bzr branch under "48hours" (tomorrow i'll change that folder to "help")08:28
humphreybchttps://wiki.ubuntu.com/ubuntu-manual/48hours08:29
humphreybcSo, how can you incorporate all this into your project, or your loco team?08:29
humphreybceasy, you just have to:08:29
humphreybcgenerate hype by creating facebook/twitter accounts08:29
humphreybcemail blog sites and tell them about your project or team08:30
humphreybcemail ubuntu members with a blog on Planet Ubuntu and ask them to give you some hangtime on the planet08:30
humphreybcrun an event to explain what your project or team does08:30
humphreybcif you're a loco team, attach yourself to a bigger project and ride off the wave that they're creating08:31
humphreybcand, be unique, be ambitious, be creative08:31
humphreybcbe different08:31
humphreybcoh and read jono bacons book "The Art of Community" - it's available free www.artofcommunityonline.org/08:32
humphreybc[SLIDE 4]08:32
humphreybcSo, how can you help us?08:32
humphreybcyou can help the project in a tonne of ways, from programming to artwork, to writing a chapter or editing one etc etc08:33
humphreybcbut if you don't feel confident in those roles, we are still looking for someone to help me maintain the facebook and twitter and identi.ca accounts08:33
humphreybcthe logo/screenshots need to be updated on those accounts, and we need constant tweets and updates to keep the hype reel rolling08:33
humphreybcbut if you don't feel like helping the project directly, you can also do it indirectly08:34
humphreybcif you think our project is cool, tell your friends or your loco team08:34
humphreybcor, if you have some people who fit into our target audience (parents, family members, spouse etc), give them the current Ubuntu Manual PDF and ask them to read a bit. Ask them if it makes sense, if it's easy to follow08:34
humphreybcask them how it could be better08:34
humphreybcand then email their comments to our mailing list or come into #ubuntu-manual on irc.freenode.net and tell us what they said!08:35
humphreybcsorry about the talk being a bit jumbled guys08:35
humphreybci'm going to reorganize it and write it down properly, i'll make some better slides and then i might make a youtube video of it08:35
humphreybcbut generalize it more for projects in general, not just UMP08:36
humphreybcokay, questions? :)08:36
humphreybcjazz asked: now these projects are they all volunteer, are there any paying gigs (as in career)08:41
humphreybcthat's a good question.08:42
humphreybcthe FOSS world runs on volunteering, but there are companies like Canonical and Novell who employ notable people from the community08:42
humphreybcthere's no guarantee you'll be employed by them for working on ubuntu08:42
humphreybcit's not meant to be an incentive, but it's a possibility08:43
humphreybcI do know that if you're in IT, employers like seeing open source experience08:43
humphreybcbe it volunteer or paid, all this stuff is quite acceptable as experience for your CV/resume.08:43
humphreybcyeah, it depends what you want to get out of it08:44
humphreybcI think if you're just doing it to get a job in the end, you'll never succeed.08:44
humphreybcYou need to be genuinely interested in helping out the community, working towards a goal. In our case, or my case, I want to see Ubuntu's market share increase because I think it deserves to be used in the mainstream.08:44
humphreybcOne of Ubuntu's biggest flaws is lack of education08:45
humphreybcthe operating system itself is great, but it's ill-educated users that don't know about it or how to use it that's not helping our cause08:45
humphreybcalso the fact that people have been brought up on windows/mac and they're used to that. We need to make it easier for them to switch08:45
humphreybcBut in the end, the average consumer is always wanting to get more "bang for their buck"08:46
humphreybcso if you have a $400 operating system in one hand, and a $0 one in your other hand that does all the same things as the $400 one, why wouldn't you choose the free one?08:46
humphreybcthe problem we have, is that people have one eye blinded, so they can't see the free operating system in one hand08:47
humphreybcwe need to open that eye and explain to them why it's better08:47
humphreybcand we need to help them adjust. it's not their fault that Microsoft has a monopoly and has forced us Windows all through school and in our workplace08:47
humphreybcbut that's what they are used to because this is exactly what Microsoft has done08:48
humphreybcso we need to teach them how to convert easily08:48
humphreybcand that's what we're trying to do with UMP08:48
=== ChanServ changed the topic of #ubuntu-classroom to: Welcome to the Ubuntu Classroom - http://wiki.ubuntu.com/Classroom || Support in #ubuntu || Upcoming Schedule: http://is.gd/8rtIi || Event: 48 Hours of Ubuntu Manual Learning - Current Session: LaTeX for authors and translators - Instructor: godbyk || Questions in #ubuntu-classroom-chat
godbyk[SLIDE 1] http://kevin.godby.org/ubuntu-manual/talks/latex-slides/00.html09:00
godbykHello, everyone.09:01
godbykThis talk will cover the basics of LaTeX: what you'll need to know as an author, editor, or translator.09:01
godbykYou can get handouts of this talk here: http://kevin.godby.org/ubuntu-manual/talks/latex-handout.pdf09:01
godbyk[SLIDE 2] http://kevin.godby.org/ubuntu-manual/talks/latex-slides/01.html09:01
godbykIn this talk, we'll cover a basic overview of how the Ubuntu Manual project uses LaTeX.09:02
godbyk[SLIDE 3] http://kevin.godby.org/ubuntu-manual/talks/latex-slides/02.html09:02
godbykBy this point, I'll assume that everyone knows the idea behind the Ubuntu Manual Project.09:02
godbykWe're aiming to produce a manual for beginning users in a multitude of languages.09:03
godbykOne of the most important tools we use to accomplish this is LaTeX.09:03
godbyk[SLIDE 4] http://kevin.godby.org/ubuntu-manual/talks/latex-slides/03.html09:03
godbykLaTeX has been around for over 20 years and it employs an underlying typesetting engine (TeX) that has been around for over 30 years.09:03
godbykLaTeX code is similar to HTML in that you can think of it as a markup language.09:04
godbykThe .tex files contain plain text -- all the word you want to appear in the PDF -- plus some markup that tells the typesetting program how to format the text and where it goes on the page.09:04
godbykUnlike HTML, though, TeX is a full programming language.  Luckily for you, most of the programming work has already been done, so you won't have to worry about that side of things.09:05
godbyk[SLIDE 5] http://kevin.godby.org/ubuntu-manual/talks/latex-slides/04.html09:05
godbykAll of the code is stored in .tex files.09:05
godbykThese files are just text files and can be read and edited using your favorite text editor.09:06
godbykThere are also some more advanced editors designed just for LaTeX (including Kile and TeXMaker).  Most editors have plugins to help with LaTeX code.09:06
godbykFor most of the code you'll be using with our manual, however, a plain text editor will serve just fine.09:07
godbykLaTeX commands begin with a backslash (\).09:07
godbykSome LaTeX commands take no arguments (like the \dash command we'll see later},09:07
godbykwhile others take 1 or more arguments.09:07
godbykAn example of a command and its argument is show on this slide: the \textbf command.09:08
godbykThe \textbf command takes a single argument: the test that is should set in bold-faced type.09:08
godbyk[SLIDE 6] http://kevin.godby.org/ubuntu-manual/talks/latex-slides/05.html09:08
godbykIn editing this manual, we'll avoid using the low-level bold, italics, etc. commands and instead use semantic markup.09:09
godbykSemantic markup lets us create new commands that can apply styles consistently across the entire manual.09:09
godbyk[SLIDE 7] http://kevin.godby.org/ubuntu-manual/talks/latex-slides/06.html09:09
godbykFor instance, instead of putting each menu name in bold, we've created a \menu command.09:10
godbykIf we were to decide later that we wanted menu names to appear in italics instead, we just have to edit one line of code in the style sheet instead of searching the entire manual for any menu names.09:10
godbyk[SLIDE 8] http://kevin.godby.org/ubuntu-manual/talks/latex-slides/07.html09:11
godbykWhile you can generally get away with simple typing whatever you like into the .tex file and having LaTeX make a nice-looking PDF from it, there are a few special characters you should be aware of.09:11
godbykThe most common "special character" is the quotation mark.09:12
godbykLaTeX knows about quotation marks -- it uses what are sometimes called "smart quotes" or "curly quotes".09:12
godbykThat is, the opening and closing quotation marks do not appear the same in the final document.09:12
godbykWhen you're editing the .tex files, opening quotation marks are entered using two "backticks" or grave accents.09:13
godbykThe closing quotation marks are entered using two apostrophes.09:13
godbykSo quoted material looks ``like this''.09:13
godbykAnother special character you'll find in the manual is the dash.09:13
godbykWe use the dash to interrupt a sentence -- Hi, mom! -- or to help place emphasis on an important point.09:14
godbykWhen we started writing the manual, we manually entered the dashes using three hyphens --- like this.09:14
godbykBut I've recently written a \dash command (which that no arguments) to do this for us.09:14
godbykUsing the \dash command allows us to use the proper dashes depending on the language.09:14
godbykIn US English, we use an em dash---like this---surrounded by no spaces.09:15
godbykHowever, in the UK and elsewhere, they use an en dash -- like this -- surrounded by a small space.09:15
godbykAs you're editing the manual, if you see an em dash written as ---, change it to \dash.09:15
godbyk[SLIDE 9] http://kevin.godby.org/ubuntu-manual/talks/latex-slides/08.html09:15
godbykThere are another few characters that LaTeX considers special.  These characters are normally used in LaTeX syntax.09:16
godbykIf you want one of these characters to appear as-is in the final PDF, put a backslash (\) in front of that character.09:16
godbykIf you want a backslash character itself to appear, you will need to use the \textbackslash command.09:17
godbyk(The \\ command actually inserts a line break instead of printing a backslash as you might expect.)09:17
godbyk[SLIDE 10] http://kevin.godby.org/ubuntu-manual/talks/latex-slides/09.html09:17
godbykThe document structure of the manual has been fairly well established by this point.09:18
godbykHowever, I wanted to mention these commands briefly so you'll know what they mean when you see them.09:18
godbykEach of these commands starts a new part/chapter/section of the document.09:18
godbykThey each take a single argument -- the name of the part/chapter/section.09:18
godbykThe name is automatically formatted appropriately and put into the PDF.09:18
godbykThese commands also add the entries to the table of contents automatically.09:19
godbyk[SLIDE 11] http://kevin.godby.org/ubuntu-manual/talks/latex-slides/10.html09:19
godbykLaTeX doesn't really care if you want to write a paragraph on multiple lines.  It will piece them back together into a paragraph for you.09:19
godbykTo tell LaTeX that you want to start a new paragraph, just leave a blank between paragraphs.09:20
godbykWe use short notes in the margin of the manual to tell the reader where to find more information about a topic, either online or in another part of the manual.09:20
godbykTo create these short notes, use the \marginnote command.09:20
godbykJust tell the \marginnote command what text you'd like it to place in the margin and it'll take care of t for you.  It's magic!09:21
godbyk[SLIDE 12] http://kevin.godby.org/ubuntu-manual/talks/latex-slides/11.html09:21
godbykOne more special character that you should take note of: the percent sign (%).09:21
godbykThe percent sign starts a comment.09:21
godbykLaTeX will ignore the percent sign and everything on the line after it.09:21
godbykThis is useful for making notes to yourself or another editor.  TODOs or FIXMEs, for instance.09:22
godbykIf you want a percent sign to appear in the PDF, however, you'll have to precede it with a backslash character.09:22
godbyk[SLIDE 13] http://kevin.godby.org/ubuntu-manual/talks/latex-slides/12.html09:22
godbykWhen we're providing instructions for the readers, we reference a lot of GUI elements: menu, buttons, windows, checkboxes, etc.09:23
godbykEach of these elements has its own command to help keep their appearance consistent throughout the manual.09:23
godbykThe \menu command is used to display menu names and menu items.09:23
godbykTo separate menu items, use the \then command.09:23
godbykAs you can see, writing \menu{Applications \then Accessories\then Calculator} will produce the text "Applications > Accessories > Calculator".09:24
godbykThe \menu command used to be named the \nav command.09:24
godbykIf you encounter the \nav command while editing the manual, please update it to use the \menu command instead.09:24
godbykSimilarly, there was a \menuitem command.  This should also be updated to \menu.09:25
ClassBotvdquynh asked: Is the blank space before "\then" optional or not?09:25
godbykvdquynh: The space is optional, yes.09:25
godbykThe \then command will try to remove any extra space around it before printing the arrow.09:25
godbykAre there any other questions about the \menu or \then commands?09:26
godbyk[SLIDE 14] http://kevin.godby.org/ubuntu-manual/talks/latex-slides/13.html09:26
godbykHere is a list of the other GUI element commands we have.09:26
godbykOne other outdated command is the \option command. This should be changed to the \checkbox command if you see it.09:27
godbykAre there any questions about any of these commands, what they refer to, or when they should be used?09:27
godbyk[SLIDE 15] http://kevin.godby.org/ubuntu-manual/talks/latex-slides/14.html09:27
godbykIn the second part of the manual -- the advanced part -- we introduce a few useful terminal commands.09:28
godbykTo display the command prompt, user input, and terminal output, we have a special environment that wraps around these commands.09:28
godbykThe terminal environment is started with the command \begin{terminal} and finished with the command \end{terminal}.09:29
ClassBotvdquynh asked: Could you put somewhere the list of commands to be replaced? like \option should be replaced by \checkbox, etc. ?09:29
godbykvdquynh: Yes, I will compile a list soon and post it to the mailing list.09:29
godbykInside the terminal environment, all of the text is printed in a monospaced font.09:29
godbykThe \prompt command simply prints a user-level bash prompt ($).09:30
godbykFor printing root prompts (#), you can use the \rootprompt command.09:30
godbykAny time the user is typing something into a terminal, you should put that text inside a \userinput command.09:30
godbykThe terminal output can by typed like normal text.09:31
godbykAre there any questions about the terminal environment or related commands?09:31
godbyk[SLIDE 16] http://kevin.godby.org/ubuntu-manual/talks/latex-slides/15.html09:31
godbykThere are two different types of lists that we use in the manual: numbered lists and bulleted lists.09:32
godbykThe only difference (in the code) between the two lists is their names.09:32
godbykThe bulleted list is called 'itemize', and the numbered list is called 'enumerate'.09:32
godbykYou start and end a list with the \begin and \end commands as shown.09:32
godbykEach item in the list starts with the \item command.09:33
godbykAre there any questions about the list environments?09:33
godbyk[SLIDE 17] http://kevin.godby.org/ubuntu-manual/talks/latex-slides/16.html09:33
ClassBotvdquynh asked: is there a limit in the number of characters for any \item of the list?09:33
godbykvdquynh: There is no set limit; you can ramble on for as long as you like.09:34
godbykThere are some practical considerations that may interfere if you're typing a novel as one list item, however. :-)09:34
ClassBotdvd asked: can you control the first number in the list?09:34
godbykdvd: You can, if necessary.  Do you have a specific instance in mind where you need to do this?09:35
ClassBotdvd asked: where the list is broken with a paragraph then continued09:36
godbykGotcha.  It will depend on the reason for stopping in the middle of the list.  If you encounter a situation where you'd like to do this, find me on IRC in #ubuntu-manual or email the list and I can help you out.09:36
godbykSimilar to HTML, we can include hyperlinks in the PDF.09:37
godbykWe have a couple commands that help cross-reference other chapters and sections in the manual.09:37
godbykTo cross-reference a chapter, use the \chaplink command.09:37
godbykTo cross-reference a section, use the \seclink command.09:37
godbykEach of these commands takes a single argument: the chapter/section label.09:38
godbykTo find the label for a specific chapter or section, open the .tex file containing that chapter/section.09:38
godbykImmediately after the \chapter or \section command, you will see a \label command.09:38
godbykThe argument to the label command is the same argument you'll use with the \chaplink and \seclink commands.09:38
godbykAll of the chapters have been assigned labels already.09:39
godbykOnly a few of the sections have.09:39
godbykIf the section you want to link to doesn't already have a label, you can create one.09:39
godbykRight after the \section{Why Linux Is Awesome} command, add a new command: \label{sec:why-linux-is-awesome}09:39
godbykThe style we use to create the labels is to prefix the label with "ch:" for chapters and "sec:" for sections.09:40
godbykThen follow that prefix (no spaces!) with a short version of the chapter/section names.09:40
godbykEach 'word' should be separated by a hyphen.09:40
ClassBotvdquynh asked: I'm a bit confused here : in "\chaplink{ch:installation}" where is the "\label" command ?09:41
godbykvdquynh: The \label command appears after the \chapter command in the installation.tex file.09:41
godbykSo the \label command is telling LaTeX, "Hey, call this chapter ch:installation."09:41
godbykThen the \chaplink command is used as \chaplink{ch:installation} to refer to the installation chapter.09:42
godbykAre there any other questions on \label, \chaplink, \seclink, or cross-referencing?09:42
godbyk[SLIDE 18] http://kevin.godby.org/ubuntu-manual/talks/latex-slides/17.html09:42
godbykA few quick notes for any translators in the crowd.09:43
godbykWhen you're translating the text, make sure that you do *not* translate the LaTeX commands themselves.09:43
godbykIf the word starts with a backslash (\), it should remain as-is.09:43
godbykMost of the arguments of the commands should be translated, however.09:43
godbykOne exception to this rule is that you should *not* translate the labels -- that is, don't translate the arguments to the \chaplink, \seclink, \ref, or \label commands.09:44
godbyk[SLIDE 19] http://kevin.godby.org/ubuntu-manual/talks/latex-slides/18.html09:44
godbykIf you're translating it to a new language, send an email to the mailing list, please.09:44
godbykIt gives me a heads up so I can be sure that your language is supported and can be compiled.09:45
godbykAre there any other questions about LaTeX?09:45
ClassBotvdquynh asked: I think not all fonts are supportive of every foreign language in Unicode ? Example: I often see horrible fonts used for Vietnamese in the liveCD09:46
godbykvdquynh: That's definitely true.09:46
godbykWe're hand-selected each font on a per-language basis.09:46
godbykThat way we can use the best fonts for that particular language.09:47
godbykIf you have suggestions on good fonts to use for the language you're translating to, please email them to me or hit me up in #ubuntu-manual.09:47
ClassBotdvd asked: How do you see the output of what you are doing (never used latex before)09:47
godbykdvd: Good question!09:47
godbykIf you want to see the English version of the manual, you can just run 'make' and it will generate a PDF called main.pdf.09:48
godbykIf you want to see a translated version of the manual, run "make ubuntu-manual-LANG.pdf"09:48
godbykwhere LANG is the language code for your language.09:48
godbyk(The language codes are listed in the po/ directory in our repository.)09:48
godbykTo get started with running LaTeX, check out the ubuntu-manual code from the repository, then go into the pkgs/ directory and run the install-pkgs.sh script from the terminal.09:49
godbykThis script will check to make sure you have the proper version of LaTeX installed along with all the required Ubuntu packages (mostly fonts) and LaTeX packages.09:50
godbykAre there any other LaTeX questions?09:51
ClassBotdvd asked: what about just installing latex from the repositories?09:51
godbykdvd: Unfortunately, the packages in the 9.10 repositories are too old what what we need.09:51
godbykThe packages in the Lucid repositories may be new enough -- I haven't tested them yet.09:51
godbykInstallation instructions for LaTeX are on the wiki here: https://wiki.ubuntu.com/ubuntu-manual/Prerequisites09:52
godbykAre there any other questions?09:52
godbykIf you come up with questions later (or run into problems), you can find me on IRC in the #ubuntu-manual channel.09:53
godbykYou can also email the ubuntu-manual mailing list.09:53
godbykI will try to keep the handout up-to-date and also keep the install-pkgs.sh script updated (in case we require more fonts/packages in the future).09:53
godbykIf there are no other questions, humphreybc will be with you shortly to discuss how the Ubuntu Manual Project employs Launchpad.09:54
ClassBotvdquynh asked: Can we use the Texlive 2009 step by step installation described in prerquistes for Karmic ?09:56
godbykvdquynh: Yes, you sure can.09:56
=== ChanServ changed the topic of #ubuntu-classroom to: Welcome to the Ubuntu Classroom - http://wiki.ubuntu.com/Classroom || Support in #ubuntu || Upcoming Schedule: http://is.gd/8rtIi || Event: 48 Hours of Ubuntu Manual Learning - Current Session: Using Launchpad to manage the project - Instructor: humphreybc || Questions in #ubuntu-classroom-chat
godbykhumphreybc is going to pass out and beg off his final talk.10:02
godbykIf you missed it the first time around, you can read a transcript of the presentation here: http://irclogs.ubuntu.com/2010/02/22/%23ubuntu-classroom.html10:02
godbykYou can grab a copy of his slides here: http://kevin.godby.org/ubuntu-manual/talks/launchpad.pdf10:02
godbykIf you have any questions, you can email the Ubuntu Manual Project at ubuntu-manual@lists.launchpad.net10:02
godbyk[SLIDE 1]10:03
godbykhttps://wiki.ubuntu.com/ubuntu-manual10:04
godbykhumphreybc is going to pass out and beg off his final talk.10:05
godbykIf you missed it the first time around, you can read a transcript of the presentation here: http://irclogs.ubuntu.com/2010/02/22/%23ubuntu-classroom.html10:05
godbykYou can grab a copy of his slides here: http://kevin.godby.org/ubuntu-manual/talks/launchpad.pdf10:05
godbykIf you have any questions, you can email the Ubuntu Manual Project at ubuntu-manual@lists.launchpad.net10:05
godbykhumphreybc is going to pass out and beg off his final talk.10:13
godbykIf you missed it the first time around, you can read a transcript of the presentation here: http://irclogs.ubuntu.com/2010/02/22/%23ubuntu-classroom.html10:13
godbykYou can grab a copy of his slides here: http://kevin.godby.org/ubuntu-manual/talks/launchpad.pdf10:13
godbykIf you have any questions, you can email the Ubuntu Manual Project at ubuntu-manual@lists.launchpad.net10:13
=== ChanServ changed the topic of #ubuntu-classroom to: Welcome to the Ubuntu Classroom - http://wiki.ubuntu.com/Classroom || Support in #ubuntu || Upcoming Schedule: http://is.gd/8rtIi || Event: 48 Hours of Ubuntu Manual Learning - Current Session: Finshing comments - Instructor: humphreybc || Questions in #ubuntu-classroom-chat
=== ChanServ changed the topic of #ubuntu-classroom to: Welcome to the Ubuntu Classroom - http://wiki.ubuntu.com/Classroom || Support in #ubuntu || Upcoming Schedule: http://is.gd/8rtIi
=== nhandler_ is now known as nhandler
=== mohi_away is now known as mohi1
=== ChanServ changed the topic of #ubuntu-classroom to: Welcome to the Ubuntu Classroom - http://wiki.ubuntu.com/Classroom || Support in #ubuntu || Upcoming Schedule: http://is.gd/8rtIi || Event: Learning Django - Current Session: Learning Django - Day 1 - Instructor: mhall119|work || Questions in #ubuntu-classroom-chat
mhall119|workgood afternoon everyone18:01
mhall119|workcan I see a show of hands for who's listing?18:02
mhall119|workgoing to give people a few minutes to arrive18:04
mhall119|workin the mean time, I'll go over what this series of classes is going to be18:05
mhall119|workthere will be 4 session, 1 hour each over 4 days18:05
mhall119|workthe topics to be covered on each day can be found here: https://wiki.ubuntu.com/mhall119/classes/LearningDjango18:05
mhall119|workit is meant to get you to the point where you have a working, functional Django application that you can continue to work on after this course is done18:06
mhall119|workI will be taking a different approach from some other classes18:07
mhall119|workwe won't be writing a dummy program18:07
mhall119|worknor will we be looking at an existing program18:07
mhall119|workrather, we will be building a useful project that has the potential for continued development after the end of this class18:07
mhall119|workand I hope that some of you will be a part of that continued development18:08
mhall119|workspecifically, we will be making a web application that will schedule session here in #ubuntu-classroom, so poor cjohnston won't have to spend so much time in wiki syntax ;)18:08
mhall119|workare there any questions about the course or what we're going to cover18:09
mhall119|work?18:09
mhall119|workOh, I should mention, we are using the new Classbot https://wiki.ubuntu.com/Classroom/ClassBot18:11
mhall119|workso if you start you question with "question: <text>", it'll automatically feed them to me18:11
ClassBotcjohnston asked: what is the timing schedule for the course?18:11
mhall119|workI think we are scheduled for 1500 UTC to 1600 UTC today through Friday18:12
mhall119|workcjohnston: is that correct?18:12
cjohnston1800 UTC18:12
mhall119|workany other questions?18:12
mhall119|workok, moving on then18:13
mhall119|workWhat is Django?18:13
mhall119|workDjango is a web application framework for Python18:13
mhall119|workit provides a lifecycle for HTTP request processing18:14
mhall119|workit also provides a very large collection of classes and libraries for making it easy to write web-based applications18:14
mhall119|workas well as some of the best object-relational mapping I've used18:14
mhall119|workcombined with python, it makes it very easy to start writing an application, as well as maintaining and enhancing them18:15
mhall119|worksorry, yes, 1800-1900 UTC18:16
mhall119|workDjango follows a model-view-controller style, which we will see a little of today and more in the following days18:16
mhall119|workso, where can you get Django?18:17
mhall119|workwell, if you're lucky enough to be running Ubuntu, you can apt-get install python-django18:18
mhall119|workotherwise you can download it from here: http://www.djangoproject.com/download/18:18
mhall119|workagain, if you're lucky enough to be running Ubuntu, that's all you need to do, it will be installed in your python path automatically18:19
mhall119|workif not, you will need to run the setup.py as instructed in the docs18:19
mhall119|workI'm going to assume you all are running Ubuntu, or at least some distro that makes it easy to get Django, so I won't go into the manual setup18:20
mhall119|workif you're curious about where django is installed run this: python -c "import django; print django.__file__"18:21
mhall119|workif you're ever curious about how Django does something, the source is right there for you to inspect18:22
mhall119|workany questions before we start creating our project?18:22
mhall119|workfor time, I've created a bzr repository that will walk through everything we're going to discuss18:23
mhall119|workI'll give the commands you would use, but you don't need them this time around18:23
mhall119|workokay, so the first thing you would do for a django project is "django-admin startproject $projectname"18:25
mhall119|workfor our example, I ran "django-admin startproject classroom_scheduler"18:25
mhall119|workand if you run "bzr branch -r tag:day1.3 lp:classroom-scheduler" you will get a copy of what that created18:26
mhall119|workif you "cd classroom-scheduler/classroom_scheduler" you will see the files that get created18:27
mhall119|workmanage.py is what you will use to control your django project18:28
mhall119|worksettings.py is where you configure your project (more on that next)18:28
mhall119|workand urls.py is what you use to connect a URL to the code you want to handle that request18:29
mhall119|workany questions so far?18:29
mhall119|workokay, moving right along then18:29
mhall119|worka project in django is composed of a collection of applications18:30
mhall119|workif you look at the bottom of settings.py, you will see the INSTALLED_APPS array18:30
mhall119|workthis is what tells django what applications make up this project18:30
mhall119|workand, as you can see, there's already some helpful applications installed for you18:31
mhall119|worksince a project doesn't do much without applications, our next step is to create an application for the functionality we want to add18:32
mhall119|workto do that, you would cd to the project directory and run "django-admin startapp $appname"18:32
mhall119|workfor this example, I ran "django-admin startapp class"18:32
mhall119|workand if you run "bzr pull -r tag:day1.4" you will get that18:33
mhall119|workand now you should see a "class" directory under the project root18:34
mhall119|workand under there you will see tests.py, views.py and models.py18:34
mhall119|workremember I said that Django uses the model-view-controller pattern?  Well here is where that happens18:35
mhall119|workfirst things first though, we need to configure our project18:35
mhall119|worklook at the top of settings.py in the project root, and you will see fields for configuring the database connection18:36
mhall119|workthis connection will be used throughout Django18:36
ClassBotsucotronic asked: is the tests.py some kind of unit testing?18:36
mhall119|workI believe so, that's something new that I haven't done much with18:37
mhall119|workhopefully there will be classes on unit testing in Django in the future18:37
mhall119|workfor this course, we're going to focus on views.py and models.py18:37
mhall119|workso, our next step is to tell our project where to find out database and application18:38
mhall119|workfor testing, it's easiest to just use 'sqlite3' as the database, so you don't have to go through the trouble of setting up a server18:38
mhall119|workso run "bzr pull -r tag:day1.5" and then look at settings.py again18:39
mhall119|workor run "bzr diff -r tag:day1.4" to see the changes18:39
mhall119|workall that I did was set the engine to use sqlite3, with the file classroom_scheduler.db as the database file18:40
mhall119|workI also added 'classroom_scheduler.class' to the INSTALLED_APPS list18:41
mhall119|worknow that Django knows where to look for the database, we have to initialize it18:41
mhall119|workto do this, run "python manage.py syncdb" from the project root18:42
mhall119|workthis will create the sqlite.db file, necessary tables, and initial values needed18:42
mhall119|workit should prompt you for an admin user, just enter a username and password you'll remember18:42
mhall119|workyou should now see the file classroom_scheduler.db in the project's root18:43
mhall119|workyou can also "sqlite3 classroom_scheduler.db" if you needed to access it directly18:43
mhall119|workalright, so now we have our project, our application, and our database, it's time to make it actually do something18:44
mhall119|workany questions before we move on?18:44
mhall119|workok, moving on18:45
mhall119|worka view in Django is nothing more than a function that takes an HttpRequest, and returns an HttpResponse18:46
mhall119|workthere's a lot more you can do in between, but that's the essence of it18:46
mhall119|workso, we're going to create our first view18:46
mhall119|workrun "bzr pull -r tag:day1.6"18:47
mhall119|worknow, when you look at classroom_scheduler/class/views.py, you should see the function "class_home"18:47
mhall119|workand you can see that it gets 'request' as an argument18:47
mhall119|workand all I'm doing is stuffing some HTML into an HttpResponse object18:48
mhall119|worknote that I had to import HttpReponse from django.http at the top of views.py18:49
mhall119|workview functions can be named anything you want, and for the most part can be placed anywhere you want, as long as python can find them18:49
mhall119|worknow that we have our view, we need to give the user a path to it18:50
mhall119|workto do that, we map it to a url in urls.py in the project root18:50
mhall119|workagain, run "bzr pull -r tag:day1.7" to get the updatre18:51
mhall119|workand "bzr diff -r tag:day1.6" to see what changed18:51
mhall119|workin this case, it was only one line in urls.py18:51
mhall119|workwith Django, you use a regular expression to match the URL of a request, and then forward that request to the view18:52
mhall119|work'^class/' will match a url like http://host:port/class/18:52
mhall119|workdjango will try each pattern in the urlpatterns list, and short-circuit on the first one that matches18:53
mhall119|workso if you want to have both '^class/(.*)' and '^class/my_view/', you need to make sure the my_view one comes first18:54
mhall119|workalright, now it's time to see what we've made18:55
mhall119|workfrom the project root, run "python manage.py runserver"18:55
mhall119|workif there aren't any problems, it should tell you that django is running on http://127.0.0.1:800018:56
mhall119|workand if you go to http://127.0.0.1:8000/class/ you should see the output of our view18:56
mhall119|workand it should look something like this: http://growingupfree.org:8001/class/18:57
mhall119|workand that concludes our first day of learning django18:57
mhall119|workare there any questions?18:57
mhall119|workokay, well then please come back tomorrow for part 2, where we will start making our models18:58
mhall119|workyou can always email me at mhall119@ubuntu.com if you have any questions later18:59
=== ChanServ changed the topic of #ubuntu-classroom to: Welcome to the Ubuntu Classroom - http://wiki.ubuntu.com/Classroom || Support in #ubuntu || Upcoming Schedule: http://is.gd/8rtIi
=== tsimpson is now known as Guest5579

Generated by irclog2html.py 2.7 by Marius Gedminas - find it at mg.pov.lt!