Looks okay and the problems you mention probably can be solved. So the only remaining issue (i keep nagging about) is differentiating within a chapter for different targets. Like:
* "I wanna try, where are the files ?" To run this sample, you'll need the last jallib pack (at least 0.2 version). You'll also find the exact code we used here<http://jallib.googlegroups.com/web/blog_16f88_board_sl_pwm_led.jal> . * is a good way to close a tutorial, but this paragraph in each chapter of a book becomes annoying. In addition to this, it would be good for consistency if there are macro's. Maybe for text like the above, but also for links etc. Joep 2009/9/5 Sebastien Lelong <[email protected]>: > Hi guys, > > Attached are DITA files + outputs, so you can have a look both source & > products. I tried to integrate some of "jalv2 & jallib - an introduction" > document, and a jalliblog post about PWM. > > I'm not that happy with HTML output, it uses frames... But I need to see how > it looks like when uploaded to a website like the one we have powered by > Drupal, with nice CSS. > > PDF Book output is nice, but have sometimes problems with margins (procuded > by book.ditamap). The other PDF, not a book according to DITA, is larger > (produced by jallib.ditamap). I still have problem to authoring this PDF. > > Please have a look and let me know what you think about this whole thing. > Let me know if you have any questions. > > > Cheers, > Seb > -- > Sébastien Lelong > http://www.sirloon.net > http://sirbot.org > > > 2009/9/4 Sebastien Lelong <[email protected]> >> >> Dita provides ditamap, a way to define Master documents where you assemble >> the différent parts. This may be thé missing part of the slide. >> >> That said we obviously need to structure our documents. Since it's "just" >> XML this can be refactored just like code and More easily than in word-like >> tools i guess. >> >> About gui since it's XML any XML editor is ok. Using dtd thé editor CAN >> know thé constraints and which éléments are allowed after others for >> instance. But this can be tricky Ex: bullet list are like in html: ul li li >> /ul . Once you're in li, if you Want another li (bullet) you need click on >> ul in the xml path, then add a new li, that because you can't have li >> élément in a li element. Just an example... See my link on xmlmind for more. >> >> About images i tried few things it seems to work ok, both in html and pdf. >> Need to be careful with maths to image files. Pdf is supported, as html, >> rtf, troff, txt, docbook ... >> >> Cheers >> Seb >> -- >> Sébastien Lelong >> >> Le 4 sept. 2009 à 13:54, Joep Suijs <[email protected]> a écrit : >> >>> >>> Hi, >>> >>> After the first part of the tutorial (same problem as Rob), I think >>> Dita provides: >>> >>> - export to different formats (i've not seen that pdf is supported, >>> but I expect it does) >>> - a selection of 'chapters' per export >>> >>> It does not have a gui editor, which makes it less easy to use (then >>> openoffice, msoffice), but will probably give more consistent results. >>> >>> I did not see anything about pictures etc. Seb, have you tried this? >>> And how does it work. >>> >>> A real chalenge is to deal with 'similar' chapters on the same topic, >>> for example ADC. A blog post is a stand-alone story in itself, with >>> hardware, software. As a chapter in the introduction document, the >>> text is slightly different (no head and tail, but maybe reference to >>> previous or coming chapters), the text is more compact (a blog needs >>> to provide all info in itself, in an introduction document, you don't >>> want to repeat the same info in each chapter, and scope ( eg for now >>> hardware info is out of scope of the introduction document). The third >>> doc is a full reference of a specific library, with many details on >>> all (well, most of the) api functionality provided. >>> This will be a chalenge regardless of the tool, but I did not see any >>> support for this in Dita. However, since it is xml, I'm sure some of >>> us can create some meta-format and a conversion tool that creates a >>> tailored dita file for each target... >>> >>> If we want a single base for all documentation, we need to use a >>> tag-based file format like xml. Probably one for each 'chapter'. Then >>> each chapter needs to provide common info, but also specific info for >>> specific targets and - as a result - a jsg-like convention for writing >>> chapters, with styles, different paragraphs etc. Finaly we need a tool >>> to convert these into the targets we want. >>> If we have this, converting the existing info to the new style will >>> not be that much work. (and if we have, I would suggest we convert the >>> blog posts to individual web pages and get rid of the blogs). >>> >>> But first, we need to agree if this is the way to go... >>> >>> Joep >>> >>> >>> >>> >>> 2009/9/4 Sebastien Lelong <[email protected]>: >>>>> >>>>>> What's your point on this? Do you understand the need and agree ? What >>>>>> other solutions can you see? >>>>> >>>>> I have no experience with desk top publishing. Simple ASCII text and >>>>> HTML has been sufficient for me and I don't want to invest much time to >>>>> learn using 'fancy' tools. But I do see a need for a documentation >>>>> tool, but let it be simple to use. >>>> >>>> Well, DITA is mainly about XML, so, using XLMMind XML Editor (XXE) for >>>> instance, you can insert some element (paragraph) easily, but you >>>> sometime >>>> need to go back in the hierachy to insert a new element (you can't >>>> insert a >>>> title tag in a bullet list). >>>> >>>> So, whatever the kind of tool, there will an investment, for sure. We >>>> make >>>> it easy by providing templates, but there will be an investment. And the >>>> question is: does it worth it ? Or keeping Word files here and ASCII & >>>> HTML >>>> files there is enough ? >>>> >>>> I don't want to impose anything on this, and am obviously open to any >>>> suggestions that could fulfill our needs (which are, according to me: >>>> reuse, >>>> multiple output format, multiple contents, scriptable, versioned >>>> efficiently >>>> by SVN -- that is using plain text, easy to edit). >>>> >>>> >>>>> >>>>>> We need to decide something on this topic, which is an important one. >>>>>> One >>>>>> decision being: "postpone"... >>>>> >>>>> The longer we wait the more work for converting existing docs. DITA >>>>> seems OK as far as I can see. >>>>> >>>>> >>>> >>>> Sure. For instance I want to start writing doc about Jaluino, but I >>>> still >>>> need to have the correct tool. >>>> >>>> >>>> Cheers, >>>> Seb >>>> >>>> >>>>> >>>> >>> >>> > > > > > --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "jallib" group. To post to this group, send email to [email protected] To unsubscribe from this group, send email to [email protected] For more options, visit this group at http://groups.google.com/group/jallib?hl=en -~----------~----~----~----~------~----~------~--~---
