Thread: [brlcad-devel] DocBook Changes NeededL Cliff!
Open Source Solid Modeling CAD
Brought to you by:
brlcad
From: Tom B. <tom...@gm...> - 2013-08-30 23:24:41
|
I need to customize DB products more by type (man, article, book, etc.) and am creating an article customization xsl file. Keep an eye out to make sure I haven't hosed CMake! -Tom |
From: Tom B. <tom...@gm...> - 2013-08-30 23:54:44
|
Actually, I'm not going to do anything until we can discuss the issue. Basically the problem is that only ONE xsl stylesheet can be called by xsltproc and that file must include all the required customizations (or include other files). I had that working for my limited use (book and chunk html only) with a not-very-clean Perl system. With CMake I think we need maybe a separate xsl file for: man/html man/pdf (fo) book/html book/pdf (fo) article/html article/pdf (fo) The main reason is for fine-tuning such things as TOCs, section (chapter) font sizes and numbering (or not), etc. Books and articles are very different. (Note that some of our categories are currently the same DocBook type, but if we want them formatted differently, they will each need their own customized xsl files for both html and pdf.) BTW, I think we should split out the man page pdf products as a separate extra-extra target because man pages can easily be made into pdf's as required on *nix systems, to wit: $ man -t attributes > attributes.ps $ ps2pdf attributes.ps Best, -Tom |
From: Clifford Y. <cli...@gm...> - 2013-08-31 02:33:05
|
On Fri, Aug 30, 2013 at 7:53 PM, Tom Browder <tom...@gm...> wrote: > I had that working for my limited use (book and chunk html only) with a > not-very-clean Perl system. With CMake I think we need maybe a separate xsl > file for: > > man/html > man/pdf (fo) > book/html > book/pdf (fo) > article/html > article/pdf (fo) So these would be equivalent (roughly) to the resources/brlcad/brlcad-*-stylesheet.xsl.in files, except something like: resources/brlcad/brlcad-man-xhtml-stylesheet.xsl.in resources/brlcad/brlcad-man-fo-stylesheet.xsl.in resources/brlcad/brlcad-book-xhtml-stylesheet.xsl.in resources/brlcad/brlcad-book-fo-stylesheet.xsl.in resources/brlcad/brlcad-article-xhtml-stylesheet.xsl.in resources/brlcad/brlcad-article-fo-stylesheet.xsl.in Correct? > The main reason is for fine-tuning such things as TOCs, section (chapter) > font sizes and numbering (or not), etc. Books and articles are very > different. Sure - sounds great, in fact! I'm all for better quality output. >> (Note that some of our categories are currently the same DocBook type, but > if we want them formatted differently, they will each need their own > customized xsl files for both html and pdf.) > > BTW, I think we should split out the man page pdf products as a separate > extra-extra target because man pages can easily be made into pdf's as > required on *nix systems, to wit: > > $ man -t attributes > attributes.ps > $ ps2pdf attributes.ps The PDF man pages can already be enabled and disabled separately from the rest of the PDF docs - I don't recall if they're also a completely separate build target... If the above is what you want Tom, I can copy our existing stylesheet templates in as starting points and wire up the build to reference them correctly for each type - would that do what you need? Cliff |
From: Tom B. <tom...@gm...> - 2013-08-31 10:36:34
|
On Fri, Aug 30, 2013 at 9:32 PM, Clifford Yapp <cli...@gm...> wrote: > On Fri, Aug 30, 2013 at 7:53 PM, Tom Browder <tom...@gm...> > wrote: > With CMake I think we need maybe a separate xsl > > file for: > > man/html > ... > So these would be equivalent (roughly) to the > resources/brlcad/brlcad-*-stylesheet.xsl.in files, except something > like: > > resources/brlcad/brlcad-man-xhtml-stylesheet.xsl.in > ... > Correct? Correct! > If the above is what you want Tom, I can copy our existing stylesheet > templates in as starting points and wire up the build to reference > them correctly for each type - would that do what you need Sounds like a plan. Thanks, Cliff! -Tom |
From: Tom B. <tom...@gm...> - 2013-08-31 11:47:39
|
Cliff, I've taken the liberty of starting style sheets for the article type and added two files: doc/docbook/resources/brlcad/ brlcad-article-fo-stylesheet.xsl.in brlcad-article-xhtml-stylesheet.xsl.in I've also referenced them in: doc/docbook/CMakeLists.txt However, I haven't touched misc/CMake/DocNook.cmake (yuck). Maybe we should reorganize the doc/docbook directory a bit to emphasize and ease the job of selecting style sheets by DocBook type. Change doc/docbook/ subdirs from: articles books css lessons presentations resources specifications system to: articles books css resources and then move lessons presentations specifications system to subdir articles or books as appropriate. -Tom |
From: Tom B. <tom...@gm...> - 2013-08-31 12:18:38
|
On Sat, Aug 31, 2013 at 6:46 AM, Tom Browder <tom...@gm...> wrote: > However, I haven't touched > misc/CMake/DocNook.cmake > That's: misc/CMake/DocBook.cmake -Tom |
From: Clifford Y. <cli...@gm...> - 2013-08-31 15:17:32
|
On Sat, Aug 31, 2013 at 7:46 AM, Tom Browder <tom...@gm...> wrote: > Cliff, I've taken the liberty of starting style sheets for the article type > and added two files: > > doc/docbook/resources/brlcad/ > brlcad-article-fo-stylesheet.xsl.in > brlcad-article-xhtml-stylesheet.xsl.in > > I've also referenced them in: > > doc/docbook/CMakeLists.txt I saw - I've taken a slightly different approach. Let me know if it's workable for now. > However, I haven't touched misc/CMake/DocNook.cmake (yuck). Heh. I don't think you need to, actually. At least, things seem to be working for me here. > Maybe we should reorganize the doc/docbook directory a bit to emphasize and > ease the job of selecting style sheets by DocBook type. Change doc/docbook/ > subdirs from: > > articles > books > css > lessons > presentations > resources > specifications > system > > to: > > articles > books > css > resources > > and then move > > lessons > presentations > specifications > system > > to subdir articles or books as appropriate. Take a look at what I've got in there now and see what you think. Since presentations, specifications, etc. may reasonably have different formatting needs I can see keeping them separate in principle. I was thinking about storing non-common resources in a resources subdirectory for each document type, to make it easier to determine which stylesheet template to edit for a given type, but I was going to wait to see how much customization is really going to be needed and what needs to be done before proposing a large scale structure/logic change. For example, do we need per-document-type css and fop.xconf files? Cliff |
From: Tom B. <tom...@gm...> - 2013-08-31 15:31:03
|
On Sat, Aug 31, 2013 at 10:17 AM, Clifford Yapp <cli...@gm...> wrote: > On Sat, Aug 31, 2013 at 7:46 AM, Tom Browder <tom...@gm...> > wrote: > > Cliff, I've taken the liberty of starting style sheets for the article > type > > and added two files: > ... > Take a look at what I've got in there now and see what you think. > Since presentations, specifications, etc. may reasonably have > different formatting needs I can see keeping them separate in > I'll check it out. determine which stylesheet template to edit for a given type, but I > was going to wait to see how much customization is really going to be > needed and what needs to be done before proposing a large scale > I agree, lets just keep it as is for now. Best, -Tom P.S. I do not like gmail's new compose editor--makes it harder to do inline posting for me. |
From: Tom B. <tom...@gm...> - 2013-09-03 19:10:00
|
On Sat, Aug 31, 2013 at 10:17 AM, Clifford Yapp <cli...@gm...> wrote: > On Sat, Aug 31, 2013 at 7:46 AM, Tom Browder <tom...@gm...> > wrote: > > Cliff, I've taken the liberty of starting style sheets for the article > type > > and added two files:I saw - I've taken a slightly different approach. > Let me know if > ... > it's > workable for now. > ... > Take a look at what I've got in there now and see what you think. > It works fine! > Since presentations, specifications, etc. may reasonably have > different formatting needs I can see keeping them separate in > principle. I think the present setup is fine for now. I (or someone) needs to better segregate the common parts versus db type customizations. That resource dir shouldn't be touched too often (hopefully); but as I wrestled with the app dev, I realized that the customizations can be better organized. Best, -Tom |
From: Christopher S. M. <br...@ma...> - 2013-08-31 15:22:05
|
On Aug 31, 2013, at 7:46 AM, Tom Browder wrote: > Maybe we should reorganize the doc/docbook directory a bit to emphasize and ease the job of selecting style sheets by DocBook type. Change doc/docbook/ subdirs from: I agree that there's very little difference between articles, lessons, and (chapters of) books. In fact, I see books as being collections of other documents (articles, lessons, manpages), with distinct structural needs (TOC, appendices, indices, ..). I'd think most presentations, however, are dramatically different (in terms of content). I can see the argument for specifications and man pages (system) falling under books, but their content is more strict (must have various sections, synopsis, etc). I also generally expect a specification document to have a style substantially different, similar to an academic research paper -- which is yet another unrepresented category (though they might work as an article). Cheers! Sean |
From: Tom B. <tom...@gm...> - 2013-08-31 15:49:02
|
On Sat, Aug 31, 2013 at 10:25 AM, Christopher Sean Morrison <br...@ma...>wrote: > > On Aug 31, 2013, at 7:46 AM, Tom Browder wrote: > > Maybe we should reorganize the doc/docbook directory a bit to emphasize > and ease the job of selecting style sheets by DocBook type. Change > doc/docbook/ subdirs from: > > I made a dumb mistake in my suggestion--the man page is a third major DB type. I agree that there's very little difference between articles, lessons, and > (chapters of) books. In fact, I see books as being collections of other > documents (articles, lessons, manpages), with distinct structural needs > (TOC, appendices, indices, ..). I'd think most presentations, however, are > dramatically different (in terms of > The problem with presentations (esp. in PPT format) for me is in translating to a DB format. My motivation has been to get a usable, black-on-white, minimum-white-space doc I can print (printing colored slides is a huge waste of paper and toner). In the conversion process the article format works best but the default article section title fonts sizes are huge (again a waste to me) [see the lessons collection]. DocBook is designed for auto-maintenence and consistent formatting. Having too many customizations is a maintenance nightmare in itself. I have no suggestions for the problem except that I do suggest moving the two presentations I converted to maybe the lessons dir (which could be called tutorials) because they are all article format and I'm trying to make them more tutorial in nature. -Tom > content). > > I can see the argument for specifications and man pages (system) falling > under books, but their content is more strict (must have various sections, > synopsis, etc). I also generally expect a specification document to have a > style substantially different, similar to an academic research paper -- > which is yet another unrepresented category (though they might work as an > article). > > Cheers! > Sean > > > > ------------------------------------------------------------------------------ > Learn the latest--Visual Studio 2012, SharePoint 2013, SQL 2012, more! > Discover the easy way to master current and previous Microsoft technologies > and advance your career. Get an incredible 1,500+ hours of step-by-step > tutorial videos with LearnDevNow. Subscribe today and save! > http://pubads.g.doubleclick.net/gampad/clk?id=58040911&iu=/4140/ostg.clktrk > _______________________________________________ > BRL-CAD Developer mailing list > brl...@li... > https://lists.sourceforge.net/lists/listinfo/brlcad-devel > > |
From: Christopher S. M. <br...@ma...> - 2013-08-31 17:21:12
|
On Aug 31, 2013, at 11:48 AM, Tom Browder wrote: > The problem with presentations (esp. in PPT format) for me is in translating to a DB format. My motivation has been to get a usable, black-on-white, minimum-white-space doc I can print (printing colored slides is a huge waste of paper and toner). Sounds like your motivation is to not have a presentation, but rather the information from a presentation in article format. I'd claim that's a new document altogether. Most presentations I have would not work well in a linear "outline" format and are heavily centered around visual diagrams. Here's one from a couple years ago that I think would translate terribly to DocBook: http://www.slideshare.net/brlcad/brl-cad-anopensourceperspectivemiloss2010 It might make the most sense to just use a 3rd party service for presentations, like slideshare.net or speakerdeck, something that'll let us embed them into our website. Then the decision whether to extract critical content from a given presentation as a document/article/book/whatever, can be made independently (like in the case of the application development "presentation" which was specifically written as a tutorial). Cheers! Sean p.s. THOSE GOING TO DOC CAMP SHOULD READ THAT PRESENTATION... but you can ignore slides 27-37. |
From: Tom B. <tom...@gm...> - 2013-08-31 17:33:03
|
On Sat, Aug 31, 2013 at 12:24 PM, Christopher Sean Morrison <br...@ma...>wrote: > > On Aug 31, 2013, at 11:48 AM, Tom Browder wrote: > Sounds like your motivation is to not have a presentation, but rather the > information from a presentation in article format. I'd claim that's a new > document altogether. > That's a good point: it's no longer a presentaion! > Most presentations I have would not work well in a linear "outline" format > and are heavily centered around visual diagrams. > Agreed--both PPT's I've converted are really tutorials. > http://www.slideshare.net/brlcad/brl-cad-anopensourceperspectivemiloss2010 > Excellent--bookmarked! That will help explain my hobby/vocation to family. > It might make the most sense to just use a 3rd party service for > presentations, like slideshare.net or speakerdeck, something that'll let > us embed them into our website. Then the decision whether to extract > critical content from a given presentation as a > document/article/book/whatever, can be made independently (like in the case > of the application development "presentation" which was specifically > written as a tutorial). > Great idea. Best, -Tom |
From: Tom B. <tom...@gm...> - 2013-09-11 11:11:40
|
On Sat, Aug 31, 2013 at 12:24 PM, Christopher Sean Morrison <br...@ma...> wrote: > Most presentations I have would not work well in a linear "outline" format > and are heavily centered around visual diagrams. Here's one from a couple > years ago that I think would translate terribly to DocBook: > > http://www.slideshare.net/brlcad/brl-cad-anopensourceperspectivemiloss2010 BTW, why is BRL-CAD not listed at mil-oss.org as a DoD or Army open source project? -Tom |
From: Christopher S. M. <br...@ma...> - 2013-09-12 17:48:56
|
On Sep 11, 2013, at 7:10 AM, Tom Browder wrote: > BTW, why is BRL-CAD not listed at mil-oss.org as a DoD or Army open > source project? Because there are about 12 lists of Gov't and DoD open source codes floating around and that is just yet another (older one) that hasn't been updated in a long time. There is a far more detailed spreadsheet that I might turn into something more interesting. Cheers! Sean |
From: Christopher S. M. <br...@ma...> - 2013-09-14 13:37:33
|
On Sep 12, 2013, at 1:52 PM, Christopher Sean Morrison wrote: > > On Sep 11, 2013, at 7:10 AM, Tom Browder wrote: > >> BTW, why is BRL-CAD not listed at mil-oss.org as a DoD or Army open >> source project? > > Because there are about 12 lists of Gov't and DoD open source codes floating around and that is just yet another (older one) that hasn't been updated in a long time. There is a far more detailed spreadsheet that I might turn into something more interesting. And now BRL-CAD is listed: http://mil-oss.org/get-involved/existing-projects Cheers! Sean |