From: Paul V. <pa...@vi...> - 2004-09-08 12:52:20
|
Hi Norman, > I've built a single pdf file and the multipage (defaulthtml) for > GSEC. I've got it uploaded to a temporary site at > > http://www.bountiful.demon.co.uk/firebird/index.html. Overall, it looks very good! But see some remarks at the bottom (lengthy as usual...) > All comments, good or bad gratefully received until the end of this > week when I'm off to Greece for about 3 weeks :o) Nice! > My wife wants some sun, I'll be the one in the shade. > She won't let me take my laptop, so I won't be updating anything > after Thursday night this week. Can't you smuggle it between some shirts? :-) By the way: which Fb package did you use? I mean, because of the presence of EPOCMAN. He shouldn't be there, at least not in official packages. Greetings, Paul Vinkenoog Remarks: - Yes, good idea to make it a <book>. But you should use <chapter> elems instead of <article>s inside. Unlike the "Firebird Database Documentation" book, which is a rather loose collection of articles, your book's children belong closely together. You can leave out <articleinfo/chapterinfo> since you're the only author. - If you show a screen (i.e. a mixture of prompts / user input / computer output), use a <screen>, not a <programlisting>. The latter is for code fragments, SQL scripts or fragments, etc. - The screens in the Introduction are very informative, but I think you should show them in a later section. Throwing bulky stuff in the reader's direction at this early stage may scare them out of reading the rest. There are women and children reading this! An intro should ideally start with a couple of short paragraphs explaining what the tool is all about (like you do), possibly followed by an overview of what's to come in the rest of the sections (e.g. using itemizedlists or orderedlists). After the intro, first some sections about the most common usages (again, like you do). But I wouldn't show those lengthy screens and look-what-happens-if-you-make-a-mistake examples too early. BTW: Maybe you should mention in the intro that on some platforms (and depending on the Fb installation package) non-root users may not be able to run gsec due to filesystem permissions, regardless of whether they know the SYSDBA password or not. - ids should be all-lowercase: firebird-utilities instead of firebird-Utilities; fbutilities-gsec-intro instead of FBUtilities-gsec-intro, etc. - ids should start with the parent id, except when the parent is the <set>, or when it is a <book> consisting of <article>s that hang only loosely together (like "Firebird Database Documentation"). Litmus test is probably whether what you write is going to wind up in one PDF file. If so, give the top element (the book, in this case) an id (e.g. fbutils) and let all child ids start with that: fbutils-gsec, fbutils-gsec-intro, fbutils-gbak, fbutils-gbak-restore. (Yes, I know I sinned against this principle in the docbuild and docwrite howtos! But I was still young then :-) Will probably correct it one day) You don't have to reflect the entire hierarchy in the id once you descend below the sect1 level, otherwise you may wind up with outrageous ids like fbutils-gsec-commandline-linux-modify-usernames. But set, book, chapter, article and sect1 (or toplevel <section>) ids are used to generate the HTML file names, so try to be consistent down to and including sect1 level. (And try to keep those ids both short and informative.) -- end-o-remarks -- |
From: Norman D. <No...@Bo...> - 2004-09-09 07:52:21
|
In article <Pin...@s4...>, pa...@vi... says... Hi Paul, I've reworked the gsec document as per your comments and it is in the same place as before : http://www.bountiful.demon.co.uk/firebird/index.html The XML is there too. > > All comments, good or bad gratefully received until the end of this > > week when I'm off to Greece for about 3 weeks :o) > > Nice! > No, that's in France, I'm off to Crete :o) > By the way: which Fb package did you use? I mean, because of the > presence of EPOCMAN. He shouldn't be there, at least not in official > packages. I'm using 1.5.0.4306 which is probably a late model candidate build. I'll download the latest at some point soon. I'm not 'in production' with any databases so I'm not too worried yet. > > Remarks: > > - Yes, good idea to make it a <book>. But you should use <chapter> > elems instead of <article>s inside. Unlike the "Firebird Database > Documentation" book, which is a rather loose collection of articles, > your book's children belong closely together. > You can leave out <articleinfo/chapterinfo> since you're the > only author. > It's now a book, with chapters instead of articles, and no articleinfo either. It builds ok so I'll continue in theis mode with the rest of the commandline stuff. > - If you show a screen (i.e. a mixture of prompts / user input / > computer output), use a <screen>, not a <programlisting>. The > latter is for code fragments, SQL scripts or fragments, etc. > Done. See new version online. > - The screens in the Introduction are very informative, but I think > you should show them in a later section. Throwing bulky stuff > in the reader's direction at this early stage may scare them > out of reading the rest. There are women and children reading this! > Women and children are safe again. I've reworked the introduction and removed all the scary stuff. It's very gentle now. > An intro should ideally start with a couple of short paragraphs > explaining what the tool is all about (like you do), possibly > followed by an overview of what's to come in the rest of the > sections (e.g. using itemizedlists or orderedlists). > After the intro, first some sections about the most common usages > (again, like you do). But I wouldn't show those lengthy screens and > look-what-happens-if-you-make-a-mistake examples too early. Sorted. An overview of things to come has been added and scary stuff moved down a litle bit. > BTW: Maybe you should mention in the intro that on some platforms > (and depending on the Fb installation package) non-root users may > not be able to run gsec due to filesystem permissions, regardless > of whether they know the SYSDBA password or not. Done. > - ids should be all-lowercase: firebird-utilities instead > of firebird-Utilities; fbutilities-gsec-intro instead of > FBUtilities-gsec-intro, etc. Sorted, I've reduced the size of them too and they are all lower case. > - ids should start with the parent id, except when the parent is the > <set>, or when it is a <book> consisting of <article>s that hang > only loosely together (like "Firebird Database Documentation"). Guess what, I've done this as well. :o) <SNIP> Thanks for your assistance on my first attempts, hopefully the new version meets with 'standards' and I can get on and do some more while I still have time (ie Thursday evening !) before my holidays. Cheers, Norman. PS. The start of GBAK has slipped into the pdf and html too, best ignored for now - its a very early draft. |
From: Paul V. <pa...@vi...> - 2004-09-09 14:07:05
|
Hi Norman, > I've reworked the gsec document as per your comments and it is > in the same place as before : > > http://www.bountiful.demon.co.uk/firebird/index.html Yes, I think it's better now. One more thing though: in verbatim environments (screen, program- listing etc.) you must limit the line length to 72 characters, otherwise they run into the right margin (or even off the edge) in the PDF output. That's not something that's "wrong" in your source, it's just a practical limitation. Also, if you use leading whitespace in verbatims, it's nicer if you match the amounts. E.g. in "GSEC Commands" there are two screens shortly after one another. The first has a 7 char left margin, the second 5. (Actually I'm not even sure if you should use a <screen> here. You're not presenting this as a screen example to the user, but as an enumeration. So an <itemizedlist> would be more logical.) BTW, a tip: for lists, you can set 'spacing="compact"'. This is often nicer if the items are short. Unfortunately, it only works for the PDF output. >> Nice! >> > No, that's in France, I'm off to Crete :o) Alright, smartypants! :-) Watch out for the labyrinths... [ Mystery man: ] > I'm using 1.5.0.4306 which is probably a late model candidate build. 4306 is the official, corrected, 1.5.0 Windows installer release (4290 was the first official 1.5.0 on all platforms but the Win installer had a bug). I checked an untouched 4306 package today and EPOCMAN isn't in the security database. My guess is that some tool has added him. Better take this EPOCMAN passage out, or people will start worrying if they *don't* find him in their USERS table ;-) Greetings, Paul Vinkenoog |
From: Norman D. <No...@Bo...> - 2004-09-09 17:37:35
|
In article <Pin...@s4...>, pa...@vi... says... Hi Paul, There attempt number 3 at : http://www.bountiful.demon.co.uk/firebird/index.html > > Yes, I think it's better now. > Phew ! > One more thing though: in verbatim environments (screen, program- > listing etc.) you must limit the line length to 72 characters, OK, I've fixed the >72 character problems and it does look miles better when rendered as PDF. I was wondering how to fix that problem, I just forgot to ask. > Also, if you use leading whitespace in verbatims, it's nicer if you > match the amounts. E.g. in "GSEC Commands" there are two screens > shortly after one another. The first has a 7 char left margin, the > second 5. Must have been a cut and paste screw up on my part, those two 'screens' were lifted directly from a DOS session of GSEC -help. Sorted now - no leading spaces. > (Actually I'm not even sure if you should use a <screen> here. You're > not presenting this as a screen example to the user, but as an > enumeration. So an <itemizedlist> would be more logical.) I've sorted thoise two, and the one above which you didn't spot :o) > BTW, a tip: for lists, you can set 'spacing="compact"'. This is often > nicer if the items are short. Unfortunately, it only works for the PDF > output. Done this. I'm not sure I like the look of the output though. Seems to make the explanation paragraph too close to the line above. Still ... > > No, that's in France, I'm off to Crete :o) > > Alright, smartypants! :-) Watch out for the labyrinths... I'll do my best. Problem is, Crete (and most other Greek Islands) tend to be somewhat hilly, and I get awful vertigo when travelling on the roads. I suspect I'll just have to sit in the shade reading books - and maybe doing a bit of drawing - for a couple of weeks. > [ Mystery man: ] <SNIP> > him. Better take this EPOCMAN passage out, or people will start > worrying if they *don't* find him in their USERS table ;-) EPOCMAN, the mystery, is no more. He's still there in the display command output, but no-one will know that he is a mysterious entity. That's it then, I might get a chance to check email etc tomorrow (I tend to use Atkin for posts as I get a daily digest via email) but I'll be travelling home for the weekend in the PM and then off to places sunny next week. I'll 'see' you when I get back. Cheers, Norm. PS. Helen - good book, well worth the wait. I'm up to selectable stored procs at the moment. I notice that it is still over 1000 pages, did they put back the bits they were going to put on a downloadable 'CD' ? N. |
From: Paul V. <pa...@vi...> - 2004-09-09 22:49:04
|
Hi Norman, >> BTW, a tip: for lists, you can set 'spacing="compact"'. This is >> often nicer if the items are short. Unfortunately, it only works >> for the PDF output. > Done this. I'm not sure I like the look of the output though. Seems > to make the explanation paragraph too close to the line above. Yes, this GSEC Commands list is a great example of where you _don't_ want to use compact spacing, because the listitems themselves contain empty lines. I use compact for lists with single-line items, and *sometimes* if the items may be two or three lines. It all depends... if I'm not sure I try both and see how I like it in the PDF. After "Coming up in this chapter", you made the outer list compact and left the inner list spacious. That also doesn't look good. I would make the inner list compact, and the outer list either compact too or leave it as default. Hm, maybe I shouldn't have started about those compact lists so shortly before your holiday... > Problem is, Crete (and most other Greek Islands) tend to be somewhat > hilly, and I get awful vertigo when travelling on the roads. Too bad! > I suspect I'll just have to sit in the shade reading books - and > maybe doing a bit of drawing - for a couple of weeks. Well, whatever you do, have a great time! Greetings, Paul Vinkenoog |
From: Norman D. <No...@Bo...> - 2004-09-10 23:20:32
|
In article <Pin...@s4...>, pa...@vi... says... Hi Paul, <SNIP> > After "Coming up in this chapter", you made the outer list compact and > left the inner list spacious. That also doesn't look good. I would > make the inner list compact, and the outer list either compact too or > leave it as default. > > Hm, maybe I shouldn't have started about those compact lists so > shortly before your holiday... Sorted. Both inner and outer lists are compact being as the are single line listitems. The other itemi[sz]ed lists are normal - they look better that way as they are multi-line. Everything in 'attempt 4' uploaded to : http://www.bountiful.demon.co.uk/firebird/index.html > Well, whatever you do, have a great time! Thanks, I'll try :o) Cheers, Norm. |
From: Paul V. <pa...@vi...> - 2004-09-13 23:51:13
|
Hi Norman, > Sorted. Both inner and outer lists are compact being as the are > single line listitems. Still doesn't look good because of the blank line before the inner list. But that's not your fault: all lists have that by default, just like paras, blockquotes, etc. I've now changed the stylesheet so that compact lists have no vertical space above them. This makes the inner list look better. However, now the outer list has also lost the leading whiteline. To get it back, wrap the outer list in a <para>. This goes for all compact lists: as from now (or rather; as from the moment I commit these changes), they'll have no more "automatic" empty line above them. Wrap them in a <para> if you want it there. Greetings, Paul Vinkenoog |
From: Paul V. <pa...@vi...> - 2004-09-16 15:23:41
|
Norman, and all, I wrote: > I've now changed the stylesheet so that compact lists have no > vertical space above them. This makes the inner list look > better. However, now the outer list has also lost the leading > whiteline. To get it back, wrap the outer list in a <para>. OK, that was a dumb idea. Now you have to check every time whether a list is wrapped in a para or not. Worse, every time you toggle a list from normal to compact or back, you have to wrap/unwrap it so that the spacing is OK. So I changed that back and added something else: the stylesheet now checks if a compact list is inside another compact list (directly or indirectly). If so, the blank line above the inner list is omitted. This works fine, and you don't have to think about it. (Not committed yet.) Greetings, Paul Vinkenoog |
From: Norman D. <No...@Bo...> - 2004-09-30 11:44:22
|
In article <Pin...@so...>, pa...@vi... says... <SNIP stuff about blanks in nested lists, warpping paras etc> OK, got all that. Thanks. Does this mean that the latest GSEC 'manual' is ok now ? What about the copyright notice which currently says 'copyright Norman Dunbar' - is this correct ? I'd hate to be being restrictive in any way. Cheers, Norman. (Slightly sun tanned !) |
From: Paul V. <pa...@vi...> - 2004-09-30 23:57:05
|
Hi Norman, > Does this mean that the latest GSEC 'manual' is ok now ? Yes! The only thing that wasn't OK was the blank line in the nested compact itemizedlist, and that was caused by the stylesheets. BTW, the stylesheet updates have been committed today. And I've added another goodie wrt lists: if you *don't* specify a spacing for an inner list, it takes on the enclosing list's spacing. So you can toggle an entire list tree from normal to compact and back just by setting the outermost list's spacing attribute. Of course you can override this automatic behaviour at any level. > What about the copyright notice which currently says 'copyright > Norman Dunbar' - is this correct ? I'd hate to be being restrictive > in any way. It's correct - you own the copyright unless you explicitly give it away. But there's no need to do that. What we have to do soon, though, is to decide what OS licence would be appropriate for our docs. It would be nice (but by no means necessary) if we all used the same licence. The way it is now, people have to ask permission to redistribute our docs. (It would be the same if you left the (c) notice out, by the way. As soon as you produce a document, you own the copyright.) But that's not how it should be: our doc sources should be true Open Source, just like the engine's sources. > Cheers, > Norman. (Slightly sun tanned !) So you did come out from under that tree now and then? :-) Greetings, Paul Vinkenoog |
From: Helen B. <he...@tp...> - 2004-10-01 00:29:21
|
At 01:54 AM 1/10/2004 +0200, you wrote: >The way it is now, people have to ask permission to redistribute our >docs. (It would be the same if you left the (c) notice out, by the >way. As soon as you produce a document, you own the copyright.) But >that's not how it should be: our doc sources should be true Open >Source, just like the engine's sources. Actually, the IDPL that is being used for the new Firebird source files is ideal for the docs. It is not "copyleft" which means that anyone can add the docs unchanged to their own custom documentation without having to publish the sources of their own documentation. Licensing it is essential, since the licence makes the permission of the author ("Initial Developer" + later contributors) implicit. You actually need to add the IDPL to the Getting Started Guides, since we released those sources under IDPL and I forgot to give you a licence notice. The same applies to any of the IBP Publications stuff that is coming through. Would you like me to write a licence notice? Helen |
From: Norman D. <No...@Bo...> - 2004-10-01 07:39:34
|
In article <Pin...@so...>, pa...@vi... says... Morning Paul, > > Does this mean that the latest GSEC 'manual' is ok now ? > > Yes! The only thing that wasn't OK was the blank line in the nested > compact itemizedlist, and that was caused by the stylesheets. > Excellent - I'll get on with some more writing now :o) > BTW, the stylesheet updates have been committed today. And I've added > another goodie wrt lists: if you *don't* specify a spacing for an > inner list, it takes on the enclosing list's spacing. So you can > toggle an entire list tree from normal to compact and back just by > setting the outermost list's spacing attribute. Of course you can > override this automatic behaviour at any level. Nice. Isn't XSL great - when you know what you are doing that is. > ... you own the copyright unless you explicitly give it > away. But there's no need to do that. What we have to do soon, though, OK, I'll leave things as they are then for now, thanks. > > > Cheers, > > Norman. (Slightly sun tanned !) > > So you did come out from under that tree now and then? :-) Well, I had to go shopping with SWMBO, and walking from the beach to the tevernas and back again did expose me slightly - even with my factor 45 and my welder's helmet :o) |