[9fans] Suggestion: Programming Tutorial for /sys/doc

[9fans] Suggestion: Programming Tutorial for /sys/doc

[Pietro Gagliardi]

Hello. I've been trying out programming Plan 9 since I got the system  
up and I think I'm getting the hang of learning from man pages. I'm  
not a big fan of having to type "man -t 2 xxx | page" about 100 times  
a day to figure out something, and there are things that the man  
pages don't cover in a clear way, so I think a tutorial should be put  
in. I already started writing one, and I think it would benefit from  
being in /sys/doc. It will cover:
	- basics
	- compiler usage
	- file access
	- threads
	- graphics and controls
	- hopefully networking
	- debugging
within about 15-30 pages. Anyone like this idea? - Pietro

Re: [9fans] Suggestion: Programming Tutorial for /sys/doc

[don bailey]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

> within about 15-30 pages. Anyone like this idea? - Pietro
> 

That stuff already is in sys/doc.
Try using acme and right-clicking on results from lookman.

D

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (GNU/Linux)

iD8DBQFHKjWlyWX0NBMJYAcRAptbAJ0cYKFFWBbiVJLuRo3tiiZnaHIFhACeMdUB
89V8Vja8nIdDqSlFB+ivp4A=
=9c2O
-----END PGP SIGNATURE-----

Re: [9fans] Suggestion: Programming Tutorial for /sys/doc

[Anthony Sorace]

On 11/1/07, Pietro Gagliardi <pietro10@mac.com> wrote:
// I'm not a big fan of having to type "man -t 2 xxx | page" about 100 times
// a day to figure out something...

oh, who would be? you want 'man -P 2 xxx' instead. ;-)

// Anyone like this idea?

I certainly like the idea of a good tutorial-style introduction. The
subject matter seems to lend itself more to the wiki than /sys/doc.
Regarding your list of suggested topics, Don's right about most of
that already being in /sys/doc (or the man pages).

Re: [9fans] Suggestion: Programming Tutorial for /sys/doc

[Pietro Gagliardi]

On Nov 1, 2007, at 4:47 PM, Anthony Sorace wrote:

> I certainly like the idea of a good tutorial-style introduction. The
> subject matter seems to lend itself more to the wiki than /sys/doc.
> Regarding your list of suggested topics, Don's right about most of
> that already being in /sys/doc (or the man pages).

/sys/doc doesn't talk much about the system as far as I know - I have  
to look at lookman first. The man pages have several flaws: there are  
too many; some important stuff is hard to find; "man page jumping" is  
a problem.

Re: [9fans] Suggestion: Programming Tutorial for /sys/doc

[Federico Benavento]

did you read nemo's intro?

http://lsub.org/who/nemo/9.intro.pdf

On 11/1/07, Pietro Gagliardi <pietro10@mac.com> wrote:
> On Nov 1, 2007, at 4:47 PM, Anthony Sorace wrote:
>
> > I certainly like the idea of a good tutorial-style introduction. The
> > subject matter seems to lend itself more to the wiki than /sys/doc.
> > Regarding your list of suggested topics, Don's right about most of
> > that already being in /sys/doc (or the man pages).
>
> /sys/doc doesn't talk much about the system as far as I know - I have
> to look at lookman first. The man pages have several flaws: there are
> too many; some important stuff is hard to find; "man page jumping" is
> a problem.
>


-- 
Federico G. Benavento

Re: [9fans] Suggestion: Programming Tutorial for /sys/doc

[Iruata Souza]

since no one seemed to care, I'll repeat fgb:
did you tried nemo's intro?

http://lsub.org/who/nemo/9.intro.pdf

iru

Re: [9fans] Suggestion: Programming Tutorial for /sys/doc

[David Leimbach]

On Nov 2, 2007 6:10 AM, Iruata Souza <iru.muzgo@gmail.com> wrote:
> since no one seemed to care, I'll repeat fgb:
> did you tried nemo's intro?
>
> http://lsub.org/who/nemo/9.intro.pdf
>
> iru
>

I've tried it... I think it's great :-)

I can confess I've not gotten through the whole thing because my plan
9 box doesn't work anymore... and I'm unable to get one running in
VMWare fusion to continue playing around.  It still hangs at boot.
I'm using venti+fossil if it matters.  Probably should just use fossil
if it's going to be a toy I guess.

Re: [9fans] Suggestion: Programming Tutorial for /sys/doc

[erik quanstrom]

> I've tried it... I think it's great :-)
> 
> I can confess I've not gotten through the whole thing because my plan
> 9 box doesn't work anymore... and I'm unable to get one running in
> VMWare fusion to continue playing around.  It still hangs at boot.
> I'm using venti+fossil if it matters.  Probably should just use fossil
> if it's going to be a toy I guess.

would it make sense to use to the older 9load until the new one
works for more people?

- erik

Re: [9fans] Suggestion: Programming Tutorial for /sys/doc

[geoff]

The new 9load works on all the machines I was able to test it on,
including booting from USB flash disks and SATA disks, in AHCI and
non-AHCI modes.  The only way it's going to work for more people is if
the community at large uses it and helps me to understand why it
doesn't work on particular machines.

Although the BIOS booting code is generating the most error messages,
the panics are likely due to interactions with AHCI.

Re: [9fans] Suggestion: Programming Tutorial for /sys/doc

[erik quanstrom]

> The new 9load works on all the machines I was able to test it on,
> including booting from USB flash disks and SATA disks, in AHCI and
> non-AHCI modes.  The only way it's going to work for more people is if
> the community at large uses it and helps me to understand why it
> doesn't work on particular machines.

i think the new 9load is a good idea and it's nice to have more booting
options.

the problem is no actual testing is going on.  when folks can't get
the livecd booting, that's pretty much the end of the road for them.
there are very limited debugging options and there is very little 
useful information gained from the failure.

> Although the BIOS booting code is generating the most error messages,
> the panics are likely due to interactions with AHCI.

i believe none of machines with reported failures in the past day
have ahci support.  (qemu, nforce 55)  also, the machines seem to
be failing when accessing the cdrom which should be accessable in
legacy mode.

anyway, what is the answer for folks who are having problems with
the current livecd?

- erik

Re: [9fans] Suggestion: Programming Tutorial for /sys/doc

[geoff]

For now, I've added *nobiosload=1 and *noahciload=1 to most cases of
the plan9.inis that will appear in tomorrow's CD image.  With AHCI and
BIOS loading disabled, 9load should be pretty much what it was before
they were added.  Once plan 9 is installed, especially on new or
emulated machines, please boot and select a case ending in `and debug
9load' and let me know what it prints, if 9load panics.

Re: [9fans] Suggestion: Programming Tutorial for /sys/doc

[David Leimbach]

On Nov 2, 2007 12:34 PM,  <geoff@plan9.bell-labs.com> wrote:
> For now, I've added *nobiosload=1 and *noahciload=1 to most cases of
> the plan9.inis that will appear in tomorrow's CD image.  With AHCI and
> BIOS loading disabled, 9load should be pretty much what it was before
> they were added.  Once plan 9 is installed, especially on new or
> emulated machines, please boot and select a case ending in `and debug
> 9load' and let me know what it prints, if 9load panics.
>
>

Great!  I'll try again tomorrow then.

Re: [9fans] Suggestion: Programming Tutorial for /sys/doc

[Gorka Guardiola]

I tested it on qemu and it worked for me.


-- 
- curiosity sKilled the cat

Re: [9fans] Suggestion: Programming Tutorial for /sys/doc

[Sander van Dijk]

On Nov 3, 2007 3:44 AM, Gorka Guardiola <paurea@gmail.com> wrote:
> I tested it on qemu and it worked for me.

May I ask how you booted the image?

Greetings, Sander.

Re: [9fans] Suggestion: Programming Tutorial for /sys/doc

[Eldanen]

[-- Attachment #1: Type: text/plain, Size: 692 bytes --]

The Nov 3rd image didn't work for me.  But, by turning off extended IDE mode
for my HDD, I was able to get an error message in assembly rather than it
just hanging without any error message.  (Not sure if that makes it
irrelevant, but anyway.)

http://home.earthlink.net/~eldanen/pastes/dmesg
http://home.earthlink.net/~eldanen/pastes/plan9output

The following was appended to "plan9output":

FLAGS=10246 TRAP=0 ENCODE=0 PC=80030089
AX 00000000 BX 8004483c CX 00000000 DX 00000000
SI 0000020 DI 00000000 BP 80047e6c
CS 0010 DS 0008 ES 0008 FS 0008 GS 0008
CRO 80000011 CR2 00f0c05c CR3 0000c000
panic: exception/interrupt 0

Press almost any key to reset...



Eldanen

[-- Attachment #2: Type: text/html, Size: 889 bytes --]

Re: [9fans] Suggestion: Programming Tutorial for /sys/doc

[erik quanstrom]

> The Nov 3rd image didn't work for me.  But, by turning off extended IDE mode
> for my HDD, I was able to get an error message in assembly rather than it
> just hanging without any error message.  (Not sure if that makes it
> irrelevant, but anyway.)
> 
> http://home.earthlink.net/~eldanen/pastes/dmesg
> http://home.earthlink.net/~eldanen/pastes/plan9output
> 
> The following was appended to "plan9output":
> 
> FLAGS=10246 TRAP=0 ENCODE=0 PC=80030089
> AX 00000000 BX 8004483c CX 00000000 DX 00000000
> SI 0000020 DI 00000000 BP 80047e6c
> CS 0010 DS 0008 ES 0008 FS 0008 GS 0008
> CRO 80000011 CR2 00f0c05c CR3 0000c000
> panic: exception/interrupt 0
> 
> Press almost any key to reset...

it didn't print anything else, did it?  the pc indicates that these
lines should have been executed

; acid /n/sources/plan9/386/9loaddebug
/n/sources/plan9/386/9loaddebug:386 plan 9 boot image
/sys/lib/acid/port
/sys/lib/acid/386
acid: src(0x80030089)
/sys/src/boot/pc/ether.c:119

/n/sources/plan9/sys/src/boot/pc/ether.c
108 			print("ether#%d: %s: port 0x%luX irq %lud",
109 				ctlr->ctlrno, ctlr->type, ctlr->port, ctlr->irq);
[...]
118 			ctlr->rb = ialloc(sizeof(RingBuf)*ctlr->nrb, 0);
>119 			if(ctlr->ntb == 0

here's a wild stab in the dark which has bitten us for an embedded
kernel we run.  make sure to turn off legacy emulation for usb devices
in the bios.  (phoenix bios has this option in the second tab under one
of the bottom selections.)  legacy emulation can turn on system management
mode.  system management mode takes over system resources (like memory)
to run the emulation code and then puts things back.  the os is not
supposed to notice, but sometimes the emulation is not seemless.
(or perhaps we don't know all the magic spots in memory.)  either way,
it's worth a shot.

- erik

Re: [9fans] Suggestion: Programming Tutorial for /sys/doc

[Eldanen]

[-- Attachment #1: Type: text/plain, Size: 2337 bytes --]

No dice on changing the USB settings in the BIOS.  Or a bunch of other
settings on/off, that I tried.  The only thing that was able to get an error
message to show was turning off Extended IDE for my SATA HDD :/.  Strange.
Thanks, though :).

On 11/3/07, erik quanstrom <quanstro@quanstro.net> wrote:
>
> > The Nov 3rd image didn't work for me.  But, by turning off extended IDE
> mode
> > for my HDD, I was able to get an error message in assembly rather than
> it
> > just hanging without any error message.  (Not sure if that makes it
> > irrelevant, but anyway.)
> >
> > http://home.earthlink.net/~eldanen/pastes/dmesg
> > http://home.earthlink.net/~eldanen/pastes/plan9output
> >
> > The following was appended to "plan9output":
> >
> > FLAGS=10246 TRAP=0 ENCODE=0 PC=80030089
> > AX 00000000 BX 8004483c CX 00000000 DX 00000000
> > SI 0000020 DI 00000000 BP 80047e6c
> > CS 0010 DS 0008 ES 0008 FS 0008 GS 0008
> > CRO 80000011 CR2 00f0c05c CR3 0000c000
> > panic: exception/interrupt 0
> >
> > Press almost any key to reset...
>
> it didn't print anything else, did it?  the pc indicates that these
> lines should have been executed
>
> ; acid /n/sources/plan9/386/9loaddebug
> /n/sources/plan9/386/9loaddebug:386 plan 9 boot image
> /sys/lib/acid/port
> /sys/lib/acid/386
> acid: src(0x80030089)
> /sys/src/boot/pc/ether.c:119
>
> /n/sources/plan9/sys/src/boot/pc/ether.c
> 108                     print("ether#%d: %s: port 0x%luX irq %lud",
> 109                             ctlr->ctlrno, ctlr->type, ctlr->port,
> ctlr->irq);
> [...]
> 118                     ctlr->rb = ialloc(sizeof(RingBuf)*ctlr->nrb, 0);
> >119                    if(ctlr->ntb == 0
>
> here's a wild stab in the dark which has bitten us for an embedded
> kernel we run.  make sure to turn off legacy emulation for usb devices
> in the bios.  (phoenix bios has this option in the second tab under one
> of the bottom selections.)  legacy emulation can turn on system management
> mode.  system management mode takes over system resources (like memory)
> to run the emulation code and then puts things back.  the os is not
> supposed to notice, but sometimes the emulation is not seemless.
> (or perhaps we don't know all the magic spots in memory.)  either way,
> it's worth a shot.
>
> - erik
>
>

[-- Attachment #2: Type: text/html, Size: 3421 bytes --]

[9fans] Font

[Michaelian Ennis]

I'd really like to use this font in plan9. Is there a guide out there  
of what is required?
http://www.levien.com/type/myfonts/inconsolata.html

Ian

Re: [9fans] Font

[Anant Narayanan]

Michaelian Ennis wrote:
> I'd really like to use this font in plan9. Is there a guide out there of
> what is required?
> http://www.levien.com/type/myfonts/inconsolata.html

Get the freetype port from http://mirtchovski.com/p9/freetype/
Convert the font to ttf and then use ttf2subf.

--
Anant

Re: [9fans] Font

[erik quanstrom]

> Michaelian Ennis wrote:
>> I'd really like to use this font in plan9. Is there a guide out there of
>> what is required?
>> http://www.levien.com/type/myfonts/inconsolata.html
> 
> Get the freetype port from http://mirtchovski.com/p9/freetype/
> Convert the font to ttf and then use ttf2subf.

there is a copy of these converted fonts on sources
	/n/sources/contrib/quanstro/subpixel/icons.tar
and
	/n/sources/contrib/quanstro/subpixel/lib/font/bit/icons/

you will need my patch to libframe for highlighting to work
correctly.

- erik

Re: [9fans] Font

[Michaelian Ennis]

> there is a copy of these converted fonts on sources
>         /n/sources/contrib/quanstro/subpixel/icons.tar
> and
>         /n/sources/contrib/quanstro/subpixel/lib/font/bit/icons/
>
> you will need my patch to libframe for highlighting to work
> correctly.

Hey that works great.  I didn't have to apply a patch though.  Perhaps
that was done for me by my friendly neighborhood sysadmin?  :)

Ian

Re: [9fans] Font

[Martin Neubauer]

http://mirtchovski.com/p9/freetype/

has some hints on that topic.

Re: [9fans] Suggestion: Programming Tutorial for /sys/doc

[Gorka Guardiola]

On Nov 3, 2007 9:49 AM, Sander van Dijk <a.h.vandijk@gmail.com> wrote:
> On Nov 3, 2007 3:44 AM, Gorka Guardiola <paurea@gmail.com> wrote:
> > I tested it on qemu and it worked for me.
>
> May I ask how you booted the image?
>

I used a hard disk on a file. I am using a flat vmware disk as a file,
dunno if this affects. I formated it with 9fat, added a kernel and booted
from it.


-- 
- curiosity sKilled the cat

Re: [9fans] Suggestion: Programming Tutorial for /sys/doc

[David Leimbach]

On Nov 2, 2007 6:39 AM, erik quanstrom <quanstro@quanstro.net> wrote:
> > I've tried it... I think it's great :-)
> >
> > I can confess I've not gotten through the whole thing because my plan
> > 9 box doesn't work anymore... and I'm unable to get one running in
> > VMWare fusion to continue playing around.  It still hangs at boot.
> > I'm using venti+fossil if it matters.  Probably should just use fossil
> > if it's going to be a toy I guess.
>
> would it make sense to use to the older 9load until the new one
> works for more people?
>
> - erik
>

Hmmm that would explain why the liveCD portion works eh?

Re: [9fans] Suggestion: Programming Tutorial for /sys/doc

[Pietro Gagliardi]

I caught the file iru, I haven't gone 100% through that but it's  
looking good so far

On Nov 2, 2007, at 9:10 AM, Iruata Souza wrote:

> since no one seemed to care, I'll repeat fgb:
> did you tried nemo's intro?
>
> http://lsub.org/who/nemo/9.intro.pdf
>
> iru

Re: [9fans] Suggestion: Programming Tutorial for /sys/doc

[Iruata Souza]

On 11/2/07, Pietro Gagliardi <pietro10@mac.com> wrote:
> I caught the file iru, I haven't gone 100% through that but it's
> looking good so far
>

good to know and good luck!

iru

Re: [9fans] Suggestion: Programming Tutorial for /sys/doc

[Pietro Gagliardi]

By the way - thanks for the file again, it told me how to properly  
use the Look tag in acme! :-)

On Nov 2, 2007, at 9:10 AM, Iruata Souza wrote:

> since no one seemed to care, I'll repeat fgb:
> did you tried nemo's intro?
>
> http://lsub.org/who/nemo/9.intro.pdf
>
> iru

Re: [9fans] Suggestion: Programming Tutorial for /sys/doc

[Uriel]

>  "man page jumping" is a problem.

Use the plumber luke. (Specially in acme, any man page reference is a
right click away)

Re: [9fans] Suggestion: Programming Tutorial for /sys/doc

[Anthony Sorace]

On 11/1/07, Pietro Gagliardi <pietro10@mac.com> wrote:

> /sys/doc doesn't talk much about the system...

Erm, what? That's pretty much all it talks about. From your list of
topics, 9.ms gives a nice view of "basics", acid.ms gives a nice tour
of debugging (acidpaper.ms is a good read, too, but isn't really
"introductory"), comp.ms give a good view of how the compilers are
typically used in Plan 9 (as opposed to compiler.ms, which talks about
the compilers themselves),  and net/net.ms covers networking in Plan 9
very well (I thought i saw a paper on libthread in there, but I seem
to be wrong).

I'm certainly not saying that there isn't valid work to do for an
introductory document, but there's much information already out there
on the topics you're covering. Maybe I'm misunderstanding your
intentions and you want to cover neglected aspects of them or some
such.

> I have to look at lookman first.

Well, yes. Or read the index yourself, I suppose (how *would* one do
that with the online version?).

> The man pages have several flaws: there are too many;

Again, I'm afraid I don't really understand this complaint. They are
numerous, yes, because they're describing lots of different things.
They don't make for the best introduction *on their own* for that
reason, but they make an excellent reference - which is more or less
their intent.

> some important stuff is hard to find;

Sometimes, yes. lookman does a very good job, but is not perfect. Can
you give examples of the types of difficulty you've been having?

> "man page jumping" is a problem.

Why? It's certainly easy enough to do - the acme integration via
plumber is very nice. It's a "problem" in that it doesn't make for a
nice, flowing introduction, but again, that's not their intent.

My point about the man pages as regards an introductory document is
mostly that it'd be bad to needlessly duplicate effort. I'd expect an
introductory document to make extensive reference to the manual for
the topics it covers.

Re: [9fans] Suggestion: Programming Tutorial for /sys/doc

[Uriel]

> > The man pages have several flaws: there are too many;
>
> Again, I'm afraid I don't really understand this complaint. They are
> numerous, yes, because they're describing lots of different things.
> They don't make for the best introduction *on their own* for that
> reason, but they make an excellent reference - which is more or less
> their intent.

There is intro(2) is not a bad introduction either, althought it
certainly doesn't cover much.

Just thinking out loud here so I might make no sense, but I suspect
the issue is that the style of the plan9 documentation is very
different from what people have become used to expect, this days
people expects 'tutorials' and other handholding with many examples to
'copy paste' into their code and so on, which is quite different from
the Unix/Plan 9 documentation style of clear and concise information
and simple examples that help illustrate the general concepts, but
that does require the reader to actually *understand* things rather
than just follow an arbitrary set of steps.

Best wishes

uriel
>
> > some important stuff is hard to find;
>
> Sometimes, yes. lookman does a very good job, but is not perfect. Can
> you give examples of the types of difficulty you've been having?
>
> > "man page jumping" is a problem.
>
> Why? It's certainly easy enough to do - the acme integration via
> plumber is very nice. It's a "problem" in that it doesn't make for a
> nice, flowing introduction, but again, that's not their intent.
>
> My point about the man pages as regards an introductory document is
> mostly that it'd be bad to needlessly duplicate effort. I'd expect an
> introductory document to make extensive reference to the manual for
> the topics it covers.
>

Re: [9fans] Suggestion: Programming Tutorial for /sys/doc

[ISHWAR RATTAN]

Sounds good to me.

-ishwar

On Thu, 1 Nov 2007, Pietro Gagliardi wrote:

> Hello. I've been trying out programming Plan 9 since I got the system up and 
> I think I'm getting the hang of learning from man pages. I'm not a big fan of 
> having to type "man -t 2 xxx | page" about 100 times a day to figure out 
> something, and there are things that the man pages don't cover in a clear 
> way, so I think a tutorial should be put in. I already started writing one, 
> and I think it would benefit from being in /sys/doc. It will cover:
> 	- basics
> 	- compiler usage
> 	- file access
> 	- threads
> 	- graphics and controls
> 	- hopefully networking
> 	- debugging
> within about 15-30 pages. Anyone like this idea? - Pietro
>

Re: [9fans] Suggestion: Programming Tutorial for /sys/doc

[Joel C. Salomon]

On 11/1/07, Pietro Gagliardi <pietro10@mac.com> wrote:
> … so I think a tutorial should be put in. I already started writing one,
> and I think it would benefit from being in /sys/doc.

Something like a combination of Brian Kernighan's "UNIX for Beginners"
and K&R's "UNIX Programming" from the 7th Edition manual, perhaps?

--Joel

Re: [9fans] Suggestion: Programming Tutorial for /sys/doc

[fernanbolando]

-----Original Message-----
From: Pietro Gagliardi <pietro10@mac.com>
> Hello. I've been trying out programming Plan 9 since I got the system  
> up and I think I'm getting the hang of learning from man pages. I'm  
> not a big fan of having to type "man -t 2 xxx | page" about 100 times  
> a day to figure out something, and there are things that the man  
> pages don't cover in a clear way, so I think a tutorial should be put  
> in. I already started writing one, and I think it would benefit from  
> being in /sys/doc. It will cover:
> 	- basics
> 	- compiler usage
> 	- file access
> 	- threads
> 	- graphics and controls
> 	- hopefully networking
> 	- debugging
> within about 15-30 pages. Anyone like this idea? - Pietro

For someone like me who have not gotten used to the entire 
plan 9 ideas yet. Something like this would be very useful.
But I think this type of documentation should be placed in the 
wiki not in /sys/doc. Once you have learned the system, you only
need the man files as references or to get more details.

Even in linux I remove all the documentation I can find except for the 
man files. 

Re: [9fans] Suggestion: Programming Tutorial for /sys/doc

[roger peppe]

i've sometimes thought that it would be nice to have
some kind of overview of the manual pages - classifying
them into groups smaller than the main sections, and
talking about them a bit.

lookman's fine if you know what you're looking for. just
reading through the manual pages sequentially turns up
many little gems, but isn't really a quick way to go about
things.

Re: [9fans] Suggestion: Programming Tutorial for /sys/doc

[Eric Van Hensbergen]

On 11/2/07, roger peppe <rogpeppe@gmail.com> wrote:
> i've sometimes thought that it would be nice to have
> some kind of overview of the manual pages - classifying
> them into groups smaller than the main sections, and
> talking about them a bit.
>

Yeah - I've got a lib/man-guide for acme which basically does
something like this with plumbable references to the man-pages I seem
to use most.  Although maybe more of a narrative would be useful.

          -eric

Re: [9fans] Suggestion: Programming Tutorial for /sys/doc

[erik quanstrom]

> For someone like me who have not gotten used to the entire 
> plan 9 ideas yet. Something like this would be very useful.
> But I think this type of documentation should be placed in the 
> wiki not in /sys/doc. Once you have learned the system, you only
> need the man files as references or to get more details.

you mean like here: http://plan9.bell-labs.com/wiki/plan9/papers/

folks, google is your friend.

- erik

Re: [9fans] Suggestion: Programming Tutorial for /sys/doc

[Douglas A. Gwyn]

Pietro Gagliardi wrote:
> I'm not a big fan of having to type "man -t 2 xxx | page" about 100 times
> a day to figure out something,

So make a shell function or command script that lets you type
"m xxx" instead.

> and there are things that the man pages don't cover in a clear way,
> so I think a tutorial should be put in.

There are "user guide" papers describing various subsystems, etc.
and at least one good, comprehensive tutorial that I know of:

http://www.lsub.org/who/nemo/9.intro.pdf

Also check out:
http://www.magma.com.ni/moin/Plan9Tutorial

Re: [9fans] Suggestion: Programming Tutorial for /sys/doc

[Anant Narayanan]

Pietro Gagliardi wrote:
> cover in a clear way, so I think a tutorial should be put in. I already
> started writing one, and I think it would benefit from being in
>     - graphics and controls

While I am mostly able understand the other concepts you mention from
existing documentation, I find graphics (libdraw) to be somewhat
cryptic. I've always felt the need for a tutorial-style introduction on
how to do graphics in Plan 9.

The current solution seems to be mostly be: "Read the code". Which isn't
really as good.

Uriel wrote:
> Just thinking out loud here so I might make no sense, but I suspect
> the issue is that the style of the plan9 documentation is very
> different from what people have become used to expect, this days
> people expects 'tutorials' and other handholding with many examples to
> 'copy paste' into their code and so on, which is quite different from
> the Unix/Plan 9 documentation style of clear and concise information
> and simple examples that help illustrate the general concepts, but
> that does require the reader to actually *understand* things rather
> than just follow an arbitrary set of steps.

Sometimes people need hand-holding, especially when they're trying to
learn a completely new system. I am all for conventional tutorial-style
introductions to Plan 9.

Even if the tutorial shamelessly repeats a lot (all?) of the information
in the man pages and papers, redundancy in documentation never really
hurt anyone. In fact, the more, the merrier :)

Cheers,
--
Anant

Re: [9fans] Suggestion: Programming Tutorial for /sys/doc

[Pietro Gagliardi]

Here's a little bit of (heavily) commented code that simply sets up  
the screen and draws a line. This should be more than enough to get  
you started (it's almost how I started).

	/* necessary headers */
	#include <u.h>
	#include <libc.h>
	#include <draw.h>
	#include <cursor.h>

	/* main routine */
	void main(int argc, char *argv[])
	{
		int c;
		void draw_line(void);

		/* int initdraw(err_func, default_font, program_name)
			If err_func is 0, use default
			If default_font is 0, use default */
		if (initdraw(0, 0, "program name") < 0)
			sysfatal("could not initialize graphics");
		draw_line();
		for (;;) /* not the best way to wait for a key hit
				I don't want to go into events here */
			if (read(0, &c, 1) == 1)
				break;
		exits(0); /* graphics is automatically terminated */
	}

So here's how you draw a line:

	void draw_line(void)
	{
		/* this is how to create a color - see allocimage(2) for a complete  
list */
		Image *black_color = allocimage(display, Rect(0, 0, 1, 1),
			RGB24, 1, DBlack);
		Point a = Pt(3, 2), b = Pt(400, 900);

		/* line(destination, from, to, from_end_type, to_end_type, thickness,
			source_color, point_to_use);
				To get the thickness of the line, use the equation
					1 + (2 * thickness)
				In this case, the thickness is 1.
				Other choices for end types are Enddisc and Endarrow.
				Plan 9 is more powerful than this, however. You can take any
				color from any image or create more elaborate arrows with
				ARROW() as the type parameter. You can even mix and match
				types. But this is more advanced. Refer to draw(2).
		*/
		line(screen, a, Endsquare, Endsquare, 0,
			black_color, Pt(0, 0));
	}

Just stick that in the code section.

On Nov 2, 2007, at 3:12 PM, Anant Narayanan wrote:

> Pietro Gagliardi wrote:
>> cover in a clear way, so I think a tutorial should be put in. I  
>> already
>> started writing one, and I think it would benefit from being in
>>     - graphics and controls
>
> While I am mostly able understand the other concepts you mention from
> existing documentation, I find graphics (libdraw) to be somewhat
> cryptic. I've always felt the need for a tutorial-style  
> introduction on
> how to do graphics in Plan 9.
>
> The current solution seems to be mostly be: "Read the code". Which  
> isn't
> really as good.
>