Changes between Version 15 and Version 16 of HtmlToDockbookProject


Ignore:
Timestamp:
Jul 17, 2007, 9:25:59 AM (15 years ago)
Author:
paolog
Comment:

proof-reading

Legend:

Unmodified
Added
Removed
Modified

  • HtmlToDockbookProject

    v15 v16  
    44      * [ImprovingBoostDocs About this project]
    55      * [BoostDocsRepository Boost docs repository]
    6       * [UnifiedLookAndFeelProject Unified look & feel project]
    7       * [HelpingBoostAuthors Helping Boost Authors]
     6      * [UnifiedLookAndFeelProject Unified look and feel project]
     7      * [HelpingBoostAuthors Helping Boost authors]
    88      * [GlueDocsProject Glue docs project]
    9       * [StandardCppLibraryDocumentation Standard C++ Library Docs]
    10       * [DocumentationBestPractices Documentation Best Practices]
    11       * [DocumentationTools Documentation Tools]
     9      * [StandardCppLibraryDocumentation Standard C++ Library docs]
     10      * [DocumentationBestPractices Documentation best practices]
     11      * [DocumentationTools Documentation tools]
    1212      * [ImprovingBoostDocsSubprojects Subprojects]
    1313           * [BoostDocTest Boost.DocTest ]
    … …  
    1515           * [BoostKateSupport Boost Kate support]
    1616           * [BoostPdfStylesheet Boost PDF stylesheet]
    17            * [BoostSpecificWikiMacros Boost specific WikiMacros]
     17           * [BoostSpecificWikiMacros Boost-specific WikiMacros]
    1818           * [BoostTracStylesheet Boost Trac stylesheet]
    1919           * [BoostscriptProject Boostscript]
    20            * [GoogleSearchBoxProject Google Search Box project]
     20           * [GoogleSearchBoxProject Google Search box project]
    2121           * '''[HtmlToDockbookProject HTML to docbook]'''
    2222           * [QuickbookWikiProcessor Quickbook WikiProcessor]
    2323           * [QuickbookSourceStylesheetProject Quickbook source stylesheet]
    2424           * [SvgIconsSetProject SVG icons set project]
    25            * [SyntaxHighlightingProject Syntax highlighting project]
    26            * [BoostTracSyntaxColoring Trac Syntax Coloring]
    27            * [DebuggerVisualizers Debugger Visualizers]
    28       * [BrowserTestingChart Browser Testing Chart]
    29       * [LibrariesLogos Logo Playground]
     25           * [SyntaxHighlightingProject Syntax-highlighting project]
     26           * [BoostTracSyntaxColoring Trac syntax-coloring]
     27           * [DebuggerVisualizers Debugger visualizers]
     28      * [BrowserTestingChart Browser-testing chart]
     29      * [LibrariesLogos Logo playground]
    3030
    3131----
    … …  
    3535=== Problem ===
    3636
    37 In order to have a complete conversion tool, it's necessary to be able to convert existing documentation, written in HTML, to quickbook.  As this currently stand, good progress is being made on the following part of the document conversion pipeline:
     37In order to have a complete conversion tool, it is necessary to be able to convert existing documentation written in HTML to Quickbook.  As this currently stands, good progress is being made on the following parts of the document-conversion pipeline:
    3838
    3939{{{
    … …  
    4747}}}
    4848
    49 The aim of this subproject then, is to investigate some open source solutions to this problem, and try and see which one will work best for boost.
     49The aim of this subproject, then, is to investigate open-source solutions to this problem and to try and see which one will work best for Boost.
    5050
    5151=== Converting HTML to docbook XML ===
    … …  
    6767}}}
    6868
    69 Two main problems present themselves.  In the first case, what should the tool do if the original document doesn't validate as XHTML?  Secondly, there will certainly be a many-to-one mapping from HTML to docbook. Is it possible to determine a general solution for this?
     69Two main problems present themselves.  First, what should the tool do if the original document doesn't validate as XHTML?  Second, there will certainly be a many-to-one mapping from HTML to docbook. Is it possible to determine a general solution for this?
    7070
    71 === Open Source Solutions ===
     71=== Open-source solutions ===
    7272
    73 For me, I'm comfortable with the idea of recommending [http://tidy.sourceforge.net Tidy] to produce validating XHTML.  Its open source and cross platform.  Furthermore its the original author's responsibility to ensure that their input is valid and I feel that this task falls out of the scope of this sub-project.
     73For myself, I am comfortable with the idea of recommending [http://tidy.sourceforge.net Tidy] for producing validated XHTML.  It is open-source and cross-platform.  Furthermore, it is the original author's responsibility to ensure that his or her input is valid, and I feel that this task falls out of the scope of this subproject.
    7474
    75 For the second point, I have found the following resources for projects which have attempted to address this problem:
     75Regarding the second point, I have found the following resources for projects that attempt to address this problem:
    7676
    7777 1. [http://www.eecs.umich.edu/~ppadala/projects/tidy/ http://www.eecs.umich.edu/~ppadala/projects/tidy/]
    7878 2. [http://wiki.docbook.org/topic/Html2DocBook http://wiki.docbook.org/topic/Html2DocBook]
    7979
    80 The first of these seemed initially promising (and was proposed as a possible solution by Matias) but I was unable to make it compile.  This makes me wonder whether this project is dead or not.  I've sent an e-mail to the developer and I'm awaiting a response.
     80The first of these initially seemed promising (and was proposed as a possible solution by Matias) but I was unable to make it compile.  This makes me wonder whether this project is dead or not.  I have sent an email to the developer and am awaiting a response.
    8181
    82 The second of these, as an XSL stylesheet, seems the more natural solution.  Its still not perfect and doesn't completely obviate the need for manually rechecking and retagging, but I feel that using this and adapting it for own needs my be fruitful.  I haven't tried hacking the stylesheet yet (this will be the next thing I try) but of the things I've found so far this seems the most promising.
     82The second of these, as an XSL stylesheet, seems the more natural solution.  It is still not perfect and does not completely obviate the need for manual rechecking and retagging, but I feel that using this and adapting it for our own needs may be fruitful.  I have not yet tried hacking the stylesheet (this is the next thing I will try) but of the things I have found so far, this one seems the most promising.
    8383
    8484
    8585=== Conclusion (so far) ===
    8686
    87 With the (still only limited) investigation I've done so far, I think that the most natural solution for converting what is one XML format to another, is to use an XSL stylesheet.  Short of developing one specifically for this project, it is best to use the one provided in solution 2 as this has been developed by someone who already has a lot of experience with docbook (I haven't yet been in touch with him yet).  Further adapting it for boost's requirements, I feel, may be the most fruitful solution.
     87With the (still only limited) investigation I have done so far, I think that the most natural solution for converting one XML format to another is to use an XSL stylesheet.  Short of developing one specifically for this project, it is best to use the one provided in solution 2 above as this has been developed by someone who already has a lot of experience with docbook (I have not yet been in touch with him).  Further adapting it for Boost's requirements may, I feel, be the most fruitful solution.
    8888
    8989----
    9090
    91 === Active Developers ===
     91=== Active developers ===
    9292
    9393[[Br]][[Image(People:glyn_matthews.png,50)]]
    9494[[Br]]'''Glyn Matthews'''
    95 [[Br]][http://www.linkedin.com/pub/4/74/b55 Linked In Profile]
     95[[Br]][http://www.linkedin.com/pub/4/74/b55 Linked In profile]
    9696[[Br]]''glyn dot matthews at gmail dot com''
    9797
    9898----
    99 
    10099   * [ImprovingBoostDocs Improving Boost Docs]
    101100      * [ImprovingBoostDocs About this project]
    102101      * [BoostDocsRepository Boost docs repository]
    103       * [UnifiedLookAndFeelProject Unified look & feel project]
    104       * [HelpingBoostAuthors Helping Boost Authors]
     102      * [UnifiedLookAndFeelProject Unified look and feel project]
     103      * [HelpingBoostAuthors Helping Boost authors]
    105104      * [GlueDocsProject Glue docs project]
    106       * [StandardCppLibraryDocumentation Standard C++ Library Docs]
    107       * [DocumentationBestPractices Documentation Best Practices]
    108       * [DocumentationTools Documentation Tools]
     105      * [StandardCppLibraryDocumentation Standard C++ Library docs]
     106      * [DocumentationBestPractices Documentation best practices]
     107      * [DocumentationTools Documentation tools]
    109108      * [ImprovingBoostDocsSubprojects Subprojects]
    110109           * [BoostDocTest Boost.DocTest ]
    … …  
    112111           * [BoostKateSupport Boost Kate support]
    113112           * [BoostPdfStylesheet Boost PDF stylesheet]
    114            * [BoostSpecificWikiMacros Boost specific WikiMacros]
     113           * [BoostSpecificWikiMacros Boost-specific WikiMacros]
    115114           * [BoostTracStylesheet Boost Trac stylesheet]
    116115           * [BoostscriptProject Boostscript]
    117            * [GoogleSearchBoxProject Google Search Box project]
     116           * [GoogleSearchBoxProject Google Search box project]
    118117           * '''[HtmlToDockbookProject HTML to docbook]'''
    119118           * [QuickbookWikiProcessor Quickbook WikiProcessor]
    120119           * [QuickbookSourceStylesheetProject Quickbook source stylesheet]
    121120           * [SvgIconsSetProject SVG icons set project]
    122            * [SyntaxHighlightingProject Syntax highlighting project]
    123            * [BoostTracSyntaxColoring Trac Syntax Coloring]
    124            * [DebuggerVisualizers Debugger Visualizers]
    125       * [BrowserTestingChart Browser Testing Chart]
    126       * [LibrariesLogos Logo Playground]
     121           * [SyntaxHighlightingProject Syntax-highlighting project]
     122           * [BoostTracSyntaxColoring Trac syntax-coloring]
     123           * [DebuggerVisualizers Debugger visualizers]
     124      * [BrowserTestingChart Browser-testing chart]
     125      * [LibrariesLogos Logo playground]