[docbook-apps] Indexing.
I'm about to start indexing a db5 book. Reading up on the subject(Nancy C. Mulvany) and wondered if anyone has been there and done that, got the tee-shirt and found the pitfalls in docbook? Any advice from those with lots of experience of using db indexes please? regards -- Dave Pawson XSLT XSL-FO FAQ. http://www.dpawson.co.uk - To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
Re: [docbook-apps] Indexing.
Hi Dave, Am Samstag, 5. Mai 2012, 08:10:05 schrieb davep: I'm about to start indexing a db5 book. Reading up on the subject(Nancy C. Mulvany) and wondered if anyone has been there and done that, got the tee-shirt and found the pitfalls in docbook? I don't know this author, so I can only speak about the experiences of indexing my book. Any advice from those with lots of experience of using db indexes please? Are you asking more about the indexing task itself or about the technical aspect? Speaking about the indexing task itself, IHMO this is something that some books don't take it seriously enough. An index is a service to make the book more accessible to readers. I've seen lots of bad index which came just as an alibi, but with no value. So it isn't a surprise that a good index takes time and energy. When I've created the index of my book, it took lots of iterations and I guess it still isn't perfect. :) What I've learned is this: don't write and create the index simultaneously. It doesn't work (well, at least for me). Try to finish your book and when it's in a decent state, then and only then, focus on the index. If you don't have an idea what to index, look at other books. I've found O'Reilly books has mostly good indices. A good index should contain different access paths. For example, if you want to know something about namespaces in DocBook you can look it up as Namespaces DocBook or DocBook Namespaces. IMHO both are valid and needed. Apart from this, try to be consistent. Either plural or singular, but noth both. I preferred the plural form. If you are more interested in the technical aspect, that depends (heavily) on your document. I assume, you write more technical documents, right? In that case, you can automate (some) things to make the indexing more easy. For example, if you write about HTML5 you will probably use tag or sgmltag. If you use this tag consistently, you can add some of them (semi-)automatically to your index page through profiling. I've described this topic in my book: http://doccookbook.sf.net/html/en/dbc.structure.adding-indexterms.html With the help of profiling, this eases the pain of indexing and you can concentrate on the more difficult parts that can't be automated. Hope that helps and good luck with your index. :-) -- Gruß/Regards Thomas Schraitle - To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
Re: [docbook-apps] Indexing.
Hi Dave Mulvany's text is an excellent indexing manual. The Chicago Manual of Style (http://www.chicagomanualofstyle.org/home.html) has a concise chapter on indexing. A free trail is available, and this manual is usually available at a library in the reference section. I have indexed books using docbook and TEI. And my preference is docbook. I did made a note to for myself some time back that an indexterm inside a footnote caused an error. I was using oXygenXML v12 at the time. Not sure if this is still the case. I did have a problem with the placement of the indexterm but that was answered at: http://www.docbook.org/tdg51/en/html/indexterm.singular.html Whitespace around indexterm may affect placement of the IDs in PDFs generated. Here are two examples of the indexterm that have worked for me. !-- SIMPLE INDEX ENTRY EXAMPLE -- SHAKESPEAREindextermprimaryShakespeare/primary/indexterm !-- STARTOFRANGE TO ENDOFRANGE -- indexterm class=startofrange xml:id=aaa1 primary sortas= Shakespeare The Shakespeare/primary /indexterm . . . . . . . . indexterm class=endofrange startref=aaa1 / Overall I have been pretty satisfied indexing with docbook. And Dave, I know you are familiar with Bob Sagehill's book which has the following: http://www.sagehill.net/docbookxsl/GenerateIndex.html Indexing an e-text it is very easy to over index. Generally an indexer is allotted a limited number of pages for an index, but in an e-text what's a few more bits. A bigger index does not mean a better index. Happy Indexing On Sat, May 5, 2012 at 4:40 AM, davep da...@dpawson.co.uk wrote: I'm about to start indexing a db5 book. Reading up on the subject(Nancy C. Mulvany) and wondered if anyone has been there and done that, got the tee-shirt and found the pitfalls in docbook? Any advice from those with lots of experience of using db indexes please? regards -- Dave Pawson XSLT XSL-FO FAQ. http://www.dpawson.co.uk --**--**- To unsubscribe, e-mail: docbook-apps-unsubscribe@**lists.oasis-open.orgdocbook-apps-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-apps-help@lists.oasis-**open.orgdocbook-apps-h...@lists.oasis-open.org
[docbook-apps] Better rendering for programlisting
Hello world, The current rendering for verbatim environments, when line numbers are enabled, has a significant deficiency: you can't cut-and-paste the listing without also getting the line numbers and separators. Looking around at other sites with numbered program listings, the solution seems to be to use tables. Put the line numbers in the first column and the listing in the second. That works, mostly, but if anything in the listing causes a variation in line height (such as a larger callout), the numbers and the lines get out of sync. Using one-line-per-row fixes this, but then cut-and-paste doesn't work again; the selection crosses over all the columns in each row. An alternative solution uses nested divs and some slightly fancy CSS. Naturally, it doesn't work in IE. I've put an example online: http://nwalsh.com/scratch/out.html The callout graphics in the listing are intentionally broken because that was the easiest way to introduce variation. At this font-size, the callouts are actually ok. So: 1. Stick with what we have now. 2. Use the table solution and accept the limitation that all lines must always be the same height. 3. Find a way to tweak the CSS solution so that IE doesn't fall over I'm open to suggestions on 3, but I'm not likely to figure it out myself. Thoughts? Other suggestions? Be seeing you, norm -- Norman Walsh n...@nwalsh.com | Ahhh. A man with a sharp wit. http://www.oasis-open.org/docbook/ | Someone ought to take it away from Chair, DocBook Technical Committee | him before he cuts himself.--Peter | da Silva pgpMnRLPuvKqc.pgp Description: PGP signature
Re: [docbook-apps] Better rendering for programlisting
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 On 05/05/2012 08:33 AM, Norman Walsh wrote: That works, mostly, but if anything in the listing causes a variation in line height (such as a larger callout), the numbers and the lines get out of sync. Hi Norm, We encountered the line height problem when we integrated SyntaxHighlighter [1]. Our solution was to make the callout graphics slightly smaller and increase the line spacing slightly. I've posted an example [2] (scroll down to the listing with 11 callouts to see that there is no effect on the line spacing). Note: To use SyntaxHighlighter, we had to modify it so that it ignores callouts when doing the syntax highlighting. There's a slight performance hit since it adds some regular expression that have to be evaluated. Another thing we had to do to make this work is to strip out most markup from code listings. We still allow DocBook markup that ends up bolding text in the code listing, but we strip out markup that doesn't have any presentational effect. Otherwise, it would have required many regular expressions to tell SyntaxHighlighter to skip. One advantage of SyntaxHighlighter is that if you double click the listing, you can copy it without getting the alt text values for the callouts like you do with straight DocBook. David [1] http://alexgorbatchev.com/SyntaxHighlighter/ [2] http://feline.thingbag.net/SyntaxHighlighterTest/content/DB_copy_paste_examples.html -BEGIN PGP SIGNATURE- Version: GnuPG v1.4.11 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/ iQEcBAEBAgAGBQJPpTrzAAoJEMHeSXG7afUhvRYH/1u26Bh/k3jqc3KqLo4/OM9A WSs5wxKod/lpVVx3vawfsGIB4XoT82qfcJa13U+vD0/3fnqiIWa8p9zcAeOn+XNn NZ7B9rxTi+R9DizeNI9PZfjq1aw+0pvF0yV1B+cL92D9evkmeXM/ZW3J3xWiOBkW 7Gf1+5qaiqGn29F7qD6Po70e7gQKPQDt3gIvAAKpMxQqRa6wmT80xLKCR5ujzGrr nhH8QjMCRh7sTVRcS4cv3ihu79+HoysxKFELuDmZv6Da7roHP0Yn7AMIZD4wMRBP CA7qJay3kHGp4bnOJ+DjUcbOOSY22taUHGq+48t7LmcJZ+lcJApbSbRL1ti2Zs4= =N/B3 -END PGP SIGNATURE- - To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
Re: [docbook-apps] Indexing.
On 05/05/12 11:00, Thomas Schraitle wrote: Any advice from those with lots of experience of using db indexes please? Are you asking more about the indexing task itself or about the technical aspect? The docbook aspects please Thomas Speaking about the indexing task itself, IHMO this is something that some books don't take it seriously enough. An index is a service to make the book more accessible to readers. I've seen lots of bad index which came just as an alibi, but with no value. So it isn't a surprise that a good index takes time and energy. When I've created the index of my book, it took lots of iterations and I guess it still isn't perfect. :) I'm hoping I can learn about the task from this book (at least a little) If you are more interested in the technical aspect, that depends (heavily) on your document. I assume, you write more technical documents, right? In that case, you can automate (some) things to make the indexing more easy. Yes, this is what I'm interested in. And yes, it is a tech document. For example, if you write about HTML5 you will probably usetag or sgmltag. If you use this tag consistently, you can add some of them (semi-)automatically to your index page through profiling. I've described this topic in my book: http://doccookbook.sf.net/html/en/dbc.structure.adding-indexterms.html Thanks... I was thinking of a manual 'edit' (addition of indexterm) but I'll have a look at this. With the help of profiling, this eases the pain of indexing and you can concentrate on the more difficult parts that can't be automated. Hope that helps and good luck with your index. :-) Thanks Thomas regards -- Dave Pawson XSLT XSL-FO FAQ. http://www.dpawson.co.uk - To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
Re: [docbook-apps] Indexing.
On 05/05/12 12:52, PC Thoms wrote: Hi Dave Mulvany's text is an excellent indexing manual. The Chicago Manual of Style (http://www.chicagomanualofstyle.org/home.html) has a concise chapter on indexing. A free trail is available, and this manual is usually available at a library in the reference section. I have the 14th edition. Ch 17 is apposite. I have indexed books using docbook and TEI. And my preference is docbook. grin/ Me too. I did made a note to for myself some time back that anindexterm inside a footnote caused an error. I was using oXygenXML v12 at the time. Not sure if this is still the case. Footnotes aren't normally indexed is one piece of advice. So perhaps docbook is right. I did have a problem with the placement of theindexterm but that was answered at: http://www.docbook.org/tdg51/en/html/indexterm.singular.html Whitespace aroundindexterm may affect placement of the IDs in PDFs generated. This is the sort of issue to which I referred (nothing like experience?) Here are two examples of theindexterm that have worked for me. !-- SIMPLE INDEX ENTRY EXAMPLE -- SHAKESPEAREindextermprimaryShakespeare/primary/indexterm !-- STARTOFRANGE TO ENDOFRANGE -- indexterm class=startofrange xml:id=aaa1 primary sortas= Shakespeare The Shakespeare/primary /indexterm . . . . . . . . indexterm class=endofrange startref=aaa1 / I knew it existed, though I haven't used it. Overall I have been pretty satisfied indexing with docbook. And Dave, I know you are familiar with Bob Sagehill's book which has the following: http://www.sagehill.net/docbookxsl/GenerateIndex.html Indexing an e-text it is very easy to over index. Generally an indexer is allotted a limited number of pages for an index, but in an e-text what's a few more bits. A bigger index does not mean a better index. Common sense and balance? Paper (modulo 32 is not an issue in my case). Happy Indexing I'll report back! Thanks. regards -- Dave Pawson XSLT XSL-FO FAQ. http://www.dpawson.co.uk - To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
Re: [docbook-apps] Better rendering for programlisting
On 05/05/12 14:33, Norman Walsh wrote: Hello world, The current rendering for verbatim environments, when line numbers are enabled, has a significant deficiency: you can't cut-and-paste the listing without also getting the line numbers and separators. Looking around at other sites with numbered program listings, the solution seems to be to use tables. Put the line numbers in the first column and the listing in the second. That works, mostly, but if anything in the listing causes a variation in line height (such as a larger callout), the numbers and the lines get out of sync. Using one-line-per-row fixes this, but then cut-and-paste doesn't work again; the selection crosses over all the columns in each row. An alternative solution uses nested divs and some slightly fancy CSS. Naturally, it doesn't work in IE. I've put an example online: http://nwalsh.com/scratch/out.html The callout graphics in the listing are intentionally broken because that was the easiest way to introduce variation. At this font-size, the callouts are actually ok. So: 1. Stick with what we have now. 2. Use the table solution and accept the limitation that all lines must always be the same height. Why is this an issue Norm? How often in a fixed width font do users want exponents/Drop caps etc? 3. Find a way to tweak the CSS solution so that IE doesn't fall over (or chase pixie dust?) I'm open to suggestions on 3, but I'm not likely to figure it out myself. Thoughts? Other suggestions? You've obviated the line numbers by putting content in col 2... why not finish the job and put co in col 3? Then I could cut/paste? HTH regards -- Dave Pawson XSLT XSL-FO FAQ. http://www.dpawson.co.uk - To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
Re: [docbook-apps] Indexing.
Hi Dave Here is another example with quotations. This from a legacy project, which is most of my work. indexterm primary sortas=banks“Banks,” The/primary /indexterm On Sat, May 5, 2012 at 1:05 PM, davep da...@dpawson.co.uk wrote: On 05/05/12 12:52, PC Thoms wrote: Hi Dave Mulvany's text is an excellent indexing manual. The Chicago Manual of Style (http://www.**chicagomanualofstyle.org/home.* *html http://www.chicagomanualofstyle.org/home.html) has a concise chapter on indexing. A free trail is available, and this manual is usually available at a library in the reference section. I have the 14th edition. Ch 17 is apposite. I have indexed books using docbook and TEI. And my preference is docbook. grin/ Me too. I did made a note to for myself some time back that anindexterm inside a footnote caused an error. I was using oXygenXML v12 at the time. Not sure if this is still the case. Footnotes aren't normally indexed is one piece of advice. So perhaps docbook is right. I did have a problem with the placement of theindexterm but that was answered at: http://www.docbook.org/tdg51/**en/html/indexterm.singular.**htmlhttp://www.docbook.org/tdg51/en/html/indexterm.singular.html Whitespace aroundindexterm may affect placement of the IDs in PDFs generated. This is the sort of issue to which I referred (nothing like experience?) Here are two examples of theindexterm that have worked for me. !-- SIMPLE INDEX ENTRY EXAMPLE -- SHAKESPEAREindexterm**primaryShakespeare/primary**/indexterm !-- STARTOFRANGE TO ENDOFRANGE -- indexterm class=startofrange xml:id=aaa1 primary sortas= Shakespeare The Shakespeare/primary /indexterm . . . . . . . . indexterm class=endofrange startref=aaa1 / I knew it existed, though I haven't used it. Overall I have been pretty satisfied indexing with docbook. And Dave, I know you are familiar with Bob Sagehill's book which has the following: http://www.sagehill.net/**docbookxsl/GenerateIndex.htmlhttp://www.sagehill.net/docbookxsl/GenerateIndex.html Indexing an e-text it is very easy to over index. Generally an indexer is allotted a limited number of pages for an index, but in an e-text what's a few more bits. A bigger index does not mean a better index. Common sense and balance? Paper (modulo 32 is not an issue in my case). Happy Indexing I'll report back! Thanks. regards -- Dave Pawson XSLT XSL-FO FAQ. http://www.dpawson.co.uk --**--**- To unsubscribe, e-mail: docbook-apps-unsubscribe@**lists.oasis-open.orgdocbook-apps-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-apps-help@lists.oasis-**open.orgdocbook-apps-h...@lists.oasis-open.org
[docbook-apps] Re: Indexing.
davep da...@dpawson.co.uk writes: Are you asking more about the indexing task itself or about the technical aspect? The docbook aspects please Thomas The sources for The Definitive Guide have quite a bit of index markup from the O'Reilly copyedit. That might be a good place to look for examples. Speaking about the indexing task itself, IHMO this is something that some books don't take it seriously enough. An index is a service to make the book more accessible to readers. I've seen lots of bad index which came just as an alibi, but with no value. So it isn't a surprise that a good index takes time and energy. When I've created the index of my book, it took lots of iterations and I guess it still isn't perfect. :) Indexing is an art. Be seeing you, norm -- Norman Walsh n...@nwalsh.com | There is no kind of dishonesty http://www.oasis-open.org/docbook/ | into which otherwise good people Chair, DocBook Technical Committee | more easily and frequently fall | than that of defrauding the | government.--Benjamin Franklin pgp2y9Pk5YZcB.pgp Description: PGP signature
[docbook-apps] Re: Indexing.
davep da...@dpawson.co.uk writes: I did made a note to for myself some time back that anindexterm inside a footnote caused an error. I was using oXygenXML v12 at the time. Not sure if this is still the case. Footnotes aren't normally indexed is one piece of advice. So perhaps docbook is right. I have a vague recollection that we may have loosened that restriction. Be seeing you, norm -- Norman Walsh n...@nwalsh.com | She was mostly immensely relieved http://www.oasis-open.org/docbook/ | to think that virtually everything Chair, DocBook Technical Committee | that anybody had ever told her was | wrong. (Mrs. E. Kapelsen)--Douglas | Adams pgpSgqUmlw0k9.pgp Description: PGP signature
Re: [docbook-apps] Indexing.
Dave, Regarding the markup mechanics, here are two possibly unexpected things to look out for: 1) When you are doing a range, the closing index term in the range cannot follow a section close. I.e., If you have the following para some text./para !-- indexterm ok -- /section !-- indexterm not ok -- /section Generally this is not a problem, since you can move the index term up in a case like this without changing its position in the resulting text. It happens because the grammar doesn't allow much after a section closes except another section and a couple of other elements. 2) If you have space (including newlines) between index terms, you will get extra space in the output. E.g., In Shakespeare's Hamlet,indextermprimaryShakespeare/primary/indexterm indextermprimaryHamlet/primary/indexterm indextermprimaryplays, Shakespeare/primary/indexterm everyone (nearly) dies in the end. In PDF output, you will get In Shakespeare's Hamlet, everyone (nearly) dies in the end. The ^ characters are space characters that come through in the output. You can avoid this by not leaving any space/newlines between successive index terms. In the Definitive guide, you will find things like the following, where an indexterm is opened on one line and then continued (space inside are ok): In Shakespeare's Hamlet,indextermprimaryShakespeare/primary/indextermindexterm primaryHamlet/primary/indextermindexterm primaryplays, Shakespeare/primary /indexterm everyone (nearly) dies in the end. I think this happens because the parser sees the white space between the index terms (and in front or after) as distinct instances of white space that need to be preserved. Neither is hard to avoid, but they can be frustrating (esp. the second one) if you're not expecting them. Dick Hamilton --- XML Press XML for Technical Communicators http://xmlpress.net hamil...@xmlpress.net On May 5, 2012, at 12:10 AM, davep wrote: I'm about to start indexing a db5 book. Reading up on the subject(Nancy C. Mulvany) and wondered if anyone has been there and done that, got the tee-shirt and found the pitfalls in docbook? Any advice from those with lots of experience of using db indexes please? regards -- Dave Pawson XSLT XSL-FO FAQ. http://www.dpawson.co.uk - To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org - To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
Re: [docbook-apps] Better rendering for programlisting
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 On 05/05/2012 10:38 AM, davep wrote: 1. Stick with what we have now. 2. Use the table solution and accept the limitation that all lines must always be the same height. Why is this an issue Norm? How often in a fixed width font do users want exponents/Drop caps etc? The callouts cause the lines that contain them to be a little higher than the others, causing the line numbers to become out of whack. If you have more than a couple of callouts, the code listing ends up extending beyond the line numbers and obviously the line numbers aren't accurate. I'm open to suggestions on 3, but I'm not likely to figure it out myself. Thoughts? Other suggestions? You've obviated the line numbers by putting content in col 2... why not finish the job and put co in col 3? But what if the user wants to put the callout somewhere other than the end of the line? If you do that, you should just abandon callouts and refer to line numbers from a list below the code listing. Then I could cut/paste? That should be hard requirement for html outputs. David -BEGIN PGP SIGNATURE- Version: GnuPG v1.4.11 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/ iQEcBAEBAgAGBQJPpcR1AAoJEMHeSXG7afUhXKIH/1SyaZPW2wna9n9ljdoDHHar +7rrfuFZpwPsmhh8rtlIK6x7nGOTXOmMV71Q3BCdS0g0+TUlbmoqmeu5CjLHjf9+ w+9iK6qd0e7acWtym2hOClZqy11XoF5K/00DZAx3h3K2+7izumx45SKQwAtc/dES QiuyAEjcC5fh6KHMoIFXg4aaAMPCrloPKaznpgfv6GT6WA4rvwmhvjmqfvggYNkU UeTLKXUFLBO8XiJum4vHVW9nQqE/Cwhdu62RLqUGslzK23oJKVUM8UZLvJdmtWnQ 73yhf5DfepliU8VQNPvN+n/JYse3z78S89NzlBE0j3++GBVA2+BBxGpNJqQsCDY= =wPhz -END PGP SIGNATURE- - To unsubscribe, e-mail: docbook-apps-unsubscr...@lists.oasis-open.org For additional commands, e-mail: docbook-apps-h...@lists.oasis-open.org
