From: Tony Cook Date: Fri, 4 Jan 2002 03:18:07 +0000 (+0000) Subject: irc log of documentation layout discussion X-Git-Tag: Imager-0.48^2~463 X-Git-Url: http://git.imager.perl.org/imager.git/commitdiff_plain/5da58e67218b3846b9643f8c9b20fa63224fd10c irc log of documentation layout discussion --- diff --git a/design/doclayout.txt b/design/doclayout.txt new file mode 100644 index 00000000..e709ef50 --- /dev/null +++ b/design/doclayout.txt @@ -0,0 +1,132 @@ +3/1 15:41:43 I've written the beginning of replacement text for "Reading and writing images" in Imager.pm in the dev_more_iolayer branch, could you have a look and give me some feedback? +3/1 15:41:47 But the OO api is consistent so I think the impact should be minimized. +3/1 15:41:50 you da boss :) +3/1 15:42:41 and images can read or +3/1 15:42:46 missing 'be' +3/1 15:43:46 There's one point that could be added about filetypes +3/1 15:43:52 maybe I do something else for a bit +3/1 15:43:56 what's that? +3/1 15:44:04 You can override the sub for finding types +3/1 15:44:12 I want to add file style specific info too +3/1 15:44:26 I wondered why it was a variable +3/1 15:44:46 So instead of using extensions, a user could provide his own method (that called file for example, although that only works for files). +3/1 15:44:46 local $Imager::FORMATGUESS = \&my_format_guess; +3/1 15:44:50 Yeah. +3/1 15:45:25 Can I edit this a little? +3/1 15:45:39 This looks really great btw. +3/1 15:45:58 sure, I'll just commit the "be" +3/1 15:46:18 actually, I'll let you +3/1 15:46:27 it's a bit faster for you :) +3/1 15:46:33 okie - where should I stop reading? +3/1 15:46:49 C<$img-Eread()> generally takes two parameters, 'file' and 'type'. <-- start of the old text +3/1 15:47:26 ok - good. +3/1 15:48:04 I want to make the file type specific stuff more reference like, I haven't figured out a layout yet though +3/1 15:48:06 brb +3/1 15:51:31 back +3/1 15:51:31 The problem in writing these docs is that you want people to be able to see an overview +3/1 15:51:58 It's possible to bury people in details about all the different ways to read/write images and the formats. +3/1 15:52:07 But most people will just want the defaults ;) +3/1 15:52:16 that's why I stuck the 2 read/write examples near the top +3/1 15:53:18 I suppose I should add examples to the file/fh/fd/data/callback items +3/1 15:53:32 Well, I'm not sure that would help. +3/1 15:53:40 Maybe two pages would be nice. +3/1 15:53:44 Imager.pm +3/1 15:53:51 and Imager-Reference.pod +3/1 15:53:54 it would help for the callbacks :) +3/1 15:54:11 Then Imager.pm would have all intro stuff +3/1 15:54:24 and we could just refer to the reference for details... +3/1 15:55:22 hmm, I'd kind of expect it the other way around, Imager.pm containing reference info, and Imager/Intro.pod +3/1 15:55:48 Hmm - I just thought of it the other way because that's the way gtk does it. +3/1 15:55:53 But I have no real preference. +3/1 15:56:17 I don't know +3/1 15:57:19 Intro.pod is probably better. +3/1 15:58:32 * TonyC:#Imager looks at perldoc DBI for inspiration +3/1 15:58:48 structuring docs is hard :/ +3/1 15:59:12 what's another big module? Tk? +3/1 15:59:18 Tk is big. +3/1 15:59:25 ImageMagick ;P +3/1 15:59:46 perldoc Tk is just a table of contents +3/1 16:00:44 does it have a "getting started" section? +3/1 16:01:01 Tk::overview and Tk::UserGuide +3/1 16:02:40 perldoc POE has a small but complete example, overview and TOC +3/1 16:03:07 Yeah - it can put references into all the sub modules. +3/1 16:03:42 I can easily imagine Imager::File, maybe Imager::Draw etc +3/1 16:03:49 (as pods) +3/1 16:04:28 So - that would give us a POE like doc structure? +3/1 16:04:45 perldoc LWP has an overview, example, TOC +3/1 16:04:46 And perldoc Imager would give an intro? +3/1 16:04:57 yep, and references to other infor +3/1 16:05:01 s/r$// +3/1 16:05:57 ok - you think we should adopt a similar approach? I like it. +3/1 16:06:01 might work better for our sanity too - rather maintaining a large POD in Imager.pm, we have a relatively small example, overview, TOC and some smaller files +3/1 16:06:09 yep +3/1 16:06:32 Yeah - I think this is what we should do. +3/1 16:08:42 * Addi:#Imager commits what will now not be of much use ;) +3/1 16:08:46 It's only spelling. +3/1 16:08:51 and some silly comment. +3/1 16:08:58 ok, if this is going to a rework of that magnitude, I'll integrate the iolayer changes into the main branch, and then put the detailed file handling docs in lib/Imager/Files.pod +3/1 16:09:33 Hmmm, before that, should we work out what sections we want? +3/1 16:10:17 Files is obvious (and big enough) +3/1 16:10:19 Filters +3/1 16:10:26 Transform +3/1 16:10:40 Image types? +3/1 16:11:04 as in paletted vs rgb vs rgb16 vs rgbdouble? +3/1 16:11:09 yes. +3/1 16:11:15 And tags. +3/1 16:11:18 Hmm +3/1 16:11:21 maybe not tags... +3/1 16:11:26 It's a borderline issue. +3/1 16:11:38 the format specific tags probably belong in Files +3/1 16:11:51 Drawing +3/1 16:11:57 And then tags as such in Image formats. +3/1 16:13:03 I wonder if Transform should be split into built-ins and the engines +3/1 16:13:48 and color transformations? +3/1 16:14:21 that would be convert/copy/map ? +3/1 16:15:53 I don't know - a file with tranform(), flip(), rotate(), transform2(), matrix_transform(), copy(), convert() and map() would be pretty big +3/1 16:16:45 A lot better than current though ;) +3/1 16:17:30 scale too. +3/1 16:17:47 yep, it's just if we're splitting, I'm not sure transform2() belongs with the simple rotate(), flip() etc functions +3/1 16:18:15 true.. +3/1 16:18:18 Maybe two of those? +3/1 16:18:45 Programmable transforms? +3/1 16:18:48 transform() and transform2() seem like they should be separate +3/1 16:18:50 yep +3/1 16:19:18 I don't know what we'd call the file though :) +3/1 16:19:29 Imager::Engines maybe +3/1 16:19:51 Imager::Bonobo, Imager::Cocoa, Imager::Marketing, Imager::Hype ;) +3/1 16:20:07 heh +3/1 16:20:22 though I'm not sure what Bonobo is +3/1 16:21:03 (a monkey?) +3/1 16:21:06 It's some java component framework or something high flying thingy. +3/1 16:24:19 portable embedded documents or somethine +3/1 16:24:24 s/e$/g/ +3/1 16:24:47 Something like that - It's a 'buzzword' ;) +3/1 16:24:51 That's all I know. +3/1 16:24:58 Engine is a good term for it I guess. +3/1 16:26:02 do you prefer plurals or singular? Imager::File|Files Imager::Filter|Filters etc +3/1 16:27:08 Normally I wouldn't care +3/1 16:27:27 But I think plural would help people see they are not classes. +3/1 16:28:38 What do you think? +3/1 16:29:08 plurals make more sense for these, I think +3/1 16:33:44 Imager - Complete Example?, overview and TOC +3/1 16:33:45 Files - IO interaction, reading/writing, format specific tags +3/1 16:33:45 Filters - Filters +3/1 16:33:45 Image Formats - Direct type/Virtual, RGB(A), img16, double +3/1 16:33:45 Transformations - flip, rotate, copy, scale, convert and map +3/1 16:33:45 Engines - transform2, matrix_transform +3/1 16:34:34 Does that seem logical? +3/1 16:35:02 I'm not sure about Image Formats, maybe Image Types +3/1 16:35:15 but either could be a source of confusion +3/1 16:35:18 Image types is petter. +3/1 16:35:22 better. +3/1 16:35:32 Storage formats is confusing too. +3/1 16:35:52 drawing, forgot that. +3/1 16:36:13 we already have Imager::Transform +3/1 16:36:29 but it should be ok +3/1 16:37:31 looks good to me +3/1 16:41:46 ok - coordinate system belongs in Image Types? +3/1 16:42:16 you mean x, y, channel? +3/1 16:43:08 Yes, but also upper left hand corner . +3/1 16:43:42 maybe that would just go in Imager.pm +3/1 16:44:10 hmm, but Image Types is probably the most logical place +3/1 16:44:34 Probably both - It's good to have it in the preview.