Re: Definitive Guide - is it real?
Manfred, sorry it took me so long to respond. (I wasn't subscribed to the user list until yesterday ). On Apr 13, 2008, at 11:14 PM, Manfred Moser wrote: Jason van Zyl-2 wrote: Right, this is where the book-like features are missing from Doxia and though I would like to fix them the primary concern at hand was getting the Maven book out. Sounds like my suspicion is correct and you can currently not use Doxia to create something like the Definitive Guide. I hope I am wrong and somebody can show me how to get it going but at this stage I have the feeling I will have to learn docbook .. Here, I wrote about why we converted to DocBook: http://blogs.sonatype.com/book/2008/04/14/120817710.html I know it isn't party line in Mavenland, but I can't stand APT. Writing a 500+ page book that has to stay up to date for a few decades, you've got to think about things like roundtrip from wiki- like to pre-print back to wiki-like.IMO, if you really are writing a big book, writing it in APT would be like trying to sail the pacific in a small raft, you can certainly do it. Now, there's an idea brewing out there about creating some good roundtrip tools from doxia markup to docbook and then back again. If we ever see that, then I think that's going to be the thing that people migrate to, but I can't wait for that to materialize. -- View this message in context: http://www.nabble.com/Definitive-Guide---is-it-real--tp16656704s177p16670486.html Sent from the Maven - Users mailing list archive at Nabble.com. - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED] - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
RE: Definitive Guide - is it real?
Maybe we should add a chapter to the book to show how to make the book? -Original Message- From: Manfred Moser [mailto:[EMAIL PROTECTED] Sent: Monday, April 14, 2008 12:14 AM To: users@maven.apache.org Subject: Re: Definitive Guide - is it real? Jason van Zyl-2 wrote: Right, this is where the book-like features are missing from Doxia and though I would like to fix them the primary concern at hand was getting the Maven book out. Sounds like my suspicion is correct and you can currently not use Doxia to create something like the Definitive Guide. I hope I am wrong and somebody can show me how to get it going but at this stage I have the feeling I will have to learn docbook .. -- View this message in context: http://www.nabble.com/Definitive-Guide---is-it-real--tp16656704s177p1667 0486.html Sent from the Maven - Users mailing list archive at Nabble.com. - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED] - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Definitive Guide - is it real?
big +1. On Mon, Apr 14, 2008 at 8:23 AM, Brian E. Fox [EMAIL PROTECTED] wrote: Maybe we should add a chapter to the book to show how to make the book? -Original Message- From: Manfred Moser [mailto:[EMAIL PROTECTED] Sent: Monday, April 14, 2008 12:14 AM To: users@maven.apache.org Subject: Re: Definitive Guide - is it real? Jason van Zyl-2 wrote: Right, this is where the book-like features are missing from Doxia and though I would like to fix them the primary concern at hand was getting the Maven book out. Sounds like my suspicion is correct and you can currently not use Doxia to create something like the Definitive Guide. I hope I am wrong and somebody can show me how to get it going but at this stage I have the feeling I will have to learn docbook .. -- View this message in context: http://www.nabble.com/Definitive-Guide---is-it-real--tp16656704s177p1667 0486.html Sent from the Maven - Users mailing list archive at Nabble.com. - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED] - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED] - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Definitive Guide - is it real?
It's in the works. I think it would be better to write a book about writing a book, but only because I wanted to write that. Tim On Apr 14, 2008, at 11:07 AM, Dan Tran wrote: big +1. On Mon, Apr 14, 2008 at 8:23 AM, Brian E. Fox [EMAIL PROTECTED] wrote: Maybe we should add a chapter to the book to show how to make the book? -Original Message- From: Manfred Moser [mailto:[EMAIL PROTECTED] Sent: Monday, April 14, 2008 12:14 AM To: users@maven.apache.org Subject: Re: Definitive Guide - is it real? Jason van Zyl-2 wrote: Right, this is where the book-like features are missing from Doxia and though I would like to fix them the primary concern at hand was getting the Maven book out. Sounds like my suspicion is correct and you can currently not use Doxia to create something like the Definitive Guide. I hope I am wrong and somebody can show me how to get it going but at this stage I have the feeling I will have to learn docbook .. -- View this message in context: http://www.nabble.com/Definitive-Guide---is-it-real--tp16656704s177p1667 0486.html Sent from the Maven - Users mailing list archive at Nabble.com. - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED] - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED] - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED] - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
RE: Definitive Guide - is it real?
Brian E Fox wrote: Maybe we should add a chapter to the book to show how to make the book? That would be awesome -- View this message in context: http://www.nabble.com/Definitive-Guide---is-it-real--tp16656704s177p16682177.html Sent from the Maven - Users mailing list archive at Nabble.com. - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Definitive Guide - is it real?
Tim O'Brien wrote: Now, there's an idea brewing out there about creating some good roundtrip tools from doxia markup to docbook and then back again. If we ever see that, then I think that's going to be the thing that people migrate to, but I can't wait for that to materialize. Me neither unfortunately. Learning docbook now ;-) -- View this message in context: http://www.nabble.com/Definitive-Guide---is-it-real--tp16656704s177p16682471.html Sent from the Maven - Users mailing list archive at Nabble.com. - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Definitive Guide - is it real?
How hard it would be to have things work would be as simple as Tim giving us a page that expresses all features in docbook that we need for making the book. Once we have that we can figure out what might need to be added to Doxia. Additions would be fine, changes that bust things not fine. I'm sure we would arrive at the deficiencies list pretty quickly. With a wysiwyg tool I ultimately no long care anymore, but being able to write a book in wiki markup would certainly be pretty cool. Simple text editing using SubethaEdit on the MAC is pretty cool where you can collaboratively edit documents. But when it comes to having real wysiwyg support, hotkeys for editing then nothing beats a rich client. On 14-Apr-08, at 10:57 AM, Manfred Moser wrote: Tim O'Brien wrote: Now, there's an idea brewing out there about creating some good roundtrip tools from doxia markup to docbook and then back again. If we ever see that, then I think that's going to be the thing that people migrate to, but I can't wait for that to materialize. Me neither unfortunately. Learning docbook now ;-) -- View this message in context: http://www.nabble.com/Definitive-Guide---is-it-real--tp16656704s177p16682471.html Sent from the Maven - Users mailing list archive at Nabble.com. - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED] Thanks, Jason -- Jason van Zyl Founder, Apache Maven jason at sonatype dot com -- Simplex sigillum veri. (Simplicity is the seal of truth.) - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Definitive Guide - is it real?
Ok, maybe not. http://blogs.sonatype.com/book/2008/04/14/120817710.html I am an optimist. I still think you could do a simplified book with a wiki markup. On 14-Apr-08, at 12:38 PM, Jason van Zyl wrote: How hard it would be to have things work would be as simple as Tim giving us a page that expresses all features in docbook that we need for making the book. Once we have that we can figure out what might need to be added to Doxia. Additions would be fine, changes that bust things not fine. I'm sure we would arrive at the deficiencies list pretty quickly. With a wysiwyg tool I ultimately no long care anymore, but being able to write a book in wiki markup would certainly be pretty cool. Simple text editing using SubethaEdit on the MAC is pretty cool where you can collaboratively edit documents. But when it comes to having real wysiwyg support, hotkeys for editing then nothing beats a rich client. On 14-Apr-08, at 10:57 AM, Manfred Moser wrote: Tim O'Brien wrote: Now, there's an idea brewing out there about creating some good roundtrip tools from doxia markup to docbook and then back again. If we ever see that, then I think that's going to be the thing that people migrate to, but I can't wait for that to materialize. Me neither unfortunately. Learning docbook now ;-) -- View this message in context: http://www.nabble.com/Definitive-Guide---is-it-real--tp16656704s177p16682471.html Sent from the Maven - Users mailing list archive at Nabble.com. - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED] Thanks, Jason -- Jason van Zyl Founder, Apache Maven jason at sonatype dot com -- Simplex sigillum veri. (Simplicity is the seal of truth.) - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED] Thanks, Jason -- Jason van Zyl Founder, Apache Maven jason at sonatype dot com -- You are never dedicated to something you have complete confidence in. No one is fanatically shouting that the sun is going to rise tomorrow. They know it is going to rise tomorrow. When people are fanatically dedicated to political or religious faiths or any other kind of dogmas or goals, it's always because these dogmas or goals are in doubt. -- Robert Pirzig, Zen and the Art of Motorcycle Maintenance - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Definitive Guide - is it real?
On Sun, Apr 13, 2008 at 2:24 PM, Jason van Zyl [EMAIL PROTECTED] wrote: You could theoretically write the book in whatever you want but you'll need a docbook sink that's accurate. Once you have that then you should be able to do the same things we are. Or just write the content in docbook. There are some limitations in doxia right now and Tim is a sadist and prefers docbook so that's what we have. There are other sadists around, but we'd like to here from Tim to compare notes. Writing good quality documentation that is properly linked, with examples taken from real working code/systems is bloody hard. Any links/suggestions on how to do this better are always welcome. - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Definitive Guide - is it real?
On 13-Apr-08, at 1:14 AM, Barrie Treloar wrote: On Sun, Apr 13, 2008 at 2:24 PM, Jason van Zyl [EMAIL PROTECTED] wrote: You could theoretically write the book in whatever you want but you'll need a docbook sink that's accurate. Once you have that then you should be able to do the same things we are. Or just write the content in docbook. There are some limitations in doxia right now and Tim is a sadist and prefers docbook so that's what we have. There are other sadists around, but we'd like to here from Tim to compare notes. Tim, and O'Reilly's primary driver here is having good editing tools. There are a couple tools I know that they use. XMLMind and Antennae. Writing good quality documentation that is properly linked, with examples taken from real working code/systems is bloody hard. Any links/suggestions on how to do this better are always welcome. Right, this is where the book-like features are missing from Doxia and though I would like to fix them the primary concern at hand was getting the Maven book out. - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED] Thanks, Jason -- Jason van Zyl Founder, Apache Maven jason at sonatype dot com -- believe nothing, no matter where you read it, or who has said it, not even if i have said it, unless it agrees with your own reason and your own common sense. -- Buddha - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Definitive Guide - is it real?
Jason van Zyl-2 wrote: Hi, The content of the book has been converted to docbook as that's what O'Reilly can consume more easily. The editing tools that Tim prefers are docbook tools so he converted the source from APT to docbook. But you could use Doxia to go from whatever to docbook and then use the tools we have. We are using docbook and the docbkx-maven-plugin. I don't have any problem letting people use the tools. The book is a community service, we don't make money off it or use it as a marketing tool (we, in fact forfeit our royalties to give it away for free and you don't have to register so we don't track anyone for leads) so let Tim sort out what's what and we'll publish what we have. You could theoretically write the book in whatever you want but you'll need a docbook sink that's accurate. Once you have that then you should be able to do the same things we are. Or just write the content in docbook. There are some limitations in doxia right now and Tim is a sadist and prefers docbook so that's what we have. So the book was in apt at some stage. Were you able actually get things like images, table of contents, cross linking, nice html as well as pdf and others going? I have my doubts that the current doxia tool chain can actually do that - or I am just too dumb. I have external code nicely executed with the sql plugin as well as included in the documentaiton with the snippet macro and I produce html and pdf. But I cant get images to work and the html is one big file. If I could get images in pdf and a nice html working I would be set. I would rather not convert to docbook but if I have to I just might. Is there something like the snippet macro I could use in docbook? How painful is the learning curve for docbook? In any case it would be great to see the setup of the book source so I could replicate folder structure and other things without too much hazzle. At first glance the docbkx maven plugin doesnt exactly overflow with documentation either. I also seen the jboss maven-jdocbook-plugin used e.g. in the richfaces source and then there is the maven-docbook-plugin. Looks like there is too much overlap and I am really not sure which one to choose, Given that the definitive guide looks like what I need provided you are using some sort of snippet/include setup for the code bits I would probably go with the one you suggest... -- View this message in context: http://www.nabble.com/Definitive-Guide---is-it-real--tp16656704s177p16670484.html Sent from the Maven - Users mailing list archive at Nabble.com. - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Definitive Guide - is it real?
baerrach wrote: On Sun, Apr 13, 2008 at 2:24 PM, Jason van Zyl [EMAIL PROTECTED] wrote: There are other sadists around, but we'd like to here from Tim to compare notes. Writing good quality documentation that is properly linked, with examples taken from real working code/systems is bloody hard. Any links/suggestions on how to do this better are always welcome. Very true. Just as an example I have to write a data model documentation with diagrams and sample SQL queries. So I have external SQL files that I actually execute as part of the build using the sql plugin. That way if the schema changes, the build breaks and the documentation will hopefully be updated... -- View this message in context: http://www.nabble.com/Definitive-Guide---is-it-real--tp16656704s177p16670485.html Sent from the Maven - Users mailing list archive at Nabble.com. - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Definitive Guide - is it real?
Jason van Zyl-2 wrote: Right, this is where the book-like features are missing from Doxia and though I would like to fix them the primary concern at hand was getting the Maven book out. Sounds like my suspicion is correct and you can currently not use Doxia to create something like the Definitive Guide. I hope I am wrong and somebody can show me how to get it going but at this stage I have the feeling I will have to learn docbook .. -- View this message in context: http://www.nabble.com/Definitive-Guide---is-it-real--tp16656704s177p16670486.html Sent from the Maven - Users mailing list archive at Nabble.com. - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Definitive Guide - is it real?
Hi, The content of the book has been converted to docbook as that's what O'Reilly can consume more easily. The editing tools that Tim prefers are docbook tools so he converted the source from APT to docbook. But you could use Doxia to go from whatever to docbook and then use the tools we have. We are using docbook and the docbkx-maven-plugin. I don't have any problem letting people use the tools. The book is a community service, we don't make money off it or use it as a marketing tool (we, in fact forfeit our royalties to give it away for free and you don't have to register so we don't track anyone for leads) so let Tim sort out what's what and we'll publish what we have. You could theoretically write the book in whatever you want but you'll need a docbook sink that's accurate. Once you have that then you should be able to do the same things we are. Or just write the content in docbook. There are some limitations in doxia right now and Tim is a sadist and prefers docbook so that's what we have. On 12-Apr-08, at 9:02 PM, Manfred Moser wrote: Hi! I really appreciate the great guide Jason and gang have put together with Maven: The Definitive Guide, which you can all get here as you probably know http://sonatype.com/book/index.html As far as I believe somehow these guys are making the book with Maven. At least I hope so. I have started to write some documentation using the doxia book plugin and have run into all sorts of issues. I am able to create the book in various formats including pdf and html as well as embedding external code snippets (SQL in my case). However I have not managed to get a nice table of content and multiple html pages happeing as nicely has Sonatype has on the site. And I definitely have not managed to get any images embedded. There are all sorts of issues in JIRA and on the wiki as various documentation on the site and in the forums. So far to no avail though. So here are my questions: Can something like the Definitive Guide be done with the doxia maven plugin or should I start looking elsewhere asap? If so how? Ideally there would be an example available that does the various formats, uses all the macros, get sthe book on the site (generated with mvn site) as well as generated downloadable artifacts (I am using the assembly plugin just fine for that) and uses images and whatever else can be done with doxia. I have however not found something like it. If the book source code would be available I could just look at it is done there but I have not found anything on the web? Otherwise does any open source project use it like I mentioned so that I could download that source code and check it out. Or maybe there is some snapshot or whatever website from doxia that contains working examples? Any help would be greatly appreciated. manfred -- View this message in context: http://www.nabble.com/Definitive-Guide---is-it-real--tp16656704s177p16656704.html Sent from the Maven - Users mailing list archive at Nabble.com. - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED] Thanks, Jason -- Jason van Zyl Founder, Apache Maven jason at sonatype dot com -- We know what we are, but know not what we may be. -- Shakespeare - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
