Lucene - Core
  1. Lucene - Core
  2. LUCENE-4008

Use Java Markdown provided by Ivy to transform BUILD.txt, MIGRATE.txt,.. to simple (better readable) HTML and place under documentation.

    Details

    • Type: Improvement Improvement
    • Status: Closed
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: 4.0-ALPHA
    • Component/s: None
    • Labels:
      None
    • Lucene Fields:
      New

      Description

      The MIGRATE.txt and other files are very simple formatted and can be converted using Markdown.

      We can use e.g. pegdown (a Java Markdown converter) to make HTML out of them and place those in the HTML documentation. Theoretically, also CHANGES.txt might be processed by Markdown, we have to try out. Pegdown is extensible, so it could handle LUCENE-xxx JIRA links correctly.

      1. LUCENE-4008.patch
        4 kB
        Uwe Schindler
      2. LUCENE-4008.patch
        4 kB
        Uwe Schindler
      3. LUCENE-4008.patch
        4 kB
        Uwe Schindler
      4. LUCENE-4008.patch
        4 kB
        Uwe Schindler
      5. LUCENE-4008.patch
        57 kB
        Uwe Schindler

        Issue Links

          Activity

          Hide
          Uwe Schindler added a comment -

          Committed trunk revision: 1328978

          Show
          Uwe Schindler added a comment - Committed trunk revision: 1328978
          Hide
          Uwe Schindler added a comment -

          Attached the latest patch with MIGRATE.txt already converted:

          • MIGRATE.txt was migrated to pegdown, was very easy. There are only few things to take care: Code must be indented by TAB or four spaces, Secrion headers start with #, ##, or ###. Lists start with * or -
          • BUILD.txt was not touched or added, as you dont need build instructions anymore once you have the full documentation
          • README.txt was minimalized and only points to the HTML docu.

          We still need a system requirements page. Ideally as markdown, too.

          I will commit that now as a start.

          Show
          Uwe Schindler added a comment - Attached the latest patch with MIGRATE.txt already converted: MIGRATE.txt was migrated to pegdown, was very easy. There are only few things to take care: Code must be indented by TAB or four spaces, Secrion headers start with #, ##, or ###. Lists start with * or - BUILD.txt was not touched or added, as you dont need build instructions anymore once you have the full documentation README.txt was minimalized and only points to the HTML docu. We still need a system requirements page. Ideally as markdown, too. I will commit that now as a start.
          Hide
          Robert Muir added a comment -

          +1, i think we should just commit this (excluding CHANGES.txt for now, as changes2html looks nicer).

          I can help with the files (adding markers for headings/bullets) so they look nice, and linking them
          into the index.html docs.

          awesome idea!

          Show
          Robert Muir added a comment - +1, i think we should just commit this (excluding CHANGES.txt for now, as changes2html looks nicer). I can help with the files (adding markers for headings/bullets) so they look nice, and linking them into the index.html docs. awesome idea!
          Hide
          Uwe Schindler added a comment -

          Small improvements in the macro/javascript:

          • Use StringBuffer, so handling the large CHANGES.txt is more effective
          • Only convert markdown if target file is older than source (default <copy/> behaviour (I had the overwrite setting enabled to debug better).
          • Remove useless import
          Show
          Uwe Schindler added a comment - Small improvements in the macro/javascript: Use StringBuffer, so handling the large CHANGES.txt is more effective Only convert markdown if target file is older than source (default <copy/> behaviour (I had the overwrite setting enabled to debug better). Remove useless import
          Hide
          Uwe Schindler added a comment -

          I offered to also include CHANGES.txt as markdown interpreted (to show that it looks not too bad).

          Here new patch, also converting CHANGES.txt to the documentation directory. Also made the pegdown macro be more verbose and allow flatten.

          Show
          Uwe Schindler added a comment - I offered to also include CHANGES.txt as markdown interpreted (to show that it looks not too bad). Here new patch, also converting CHANGES.txt to the documentation directory. Also made the pegdown macro be more verbose and allow flatten.
          Hide
          Uwe Schindler added a comment -

          More compact patch and invocation using todir="" and nested filesets.

          Show
          Uwe Schindler added a comment - More compact patch and invocation using todir="" and nested filesets.
          Hide
          Uwe Schindler added a comment -

          Attached a first patch to demonstate the idea. The patch adds a new <pegdown/> macro to common-build.xml that can convert any TXT file to a HTML representation (if the syntax is fine). It has some hacks:

          • It uses the first line of the TXT file as HTML page title
          • It converts the first line to a first level heading
          • It rewrites LUCENE-xxx/SOLR-xxx identifiers to Markdown Links to JIRA

          The patch converts a few files (including CHANGES.txt!!!) to HTML using that macro and places them in build/docs, no linking at the moment.

          It is visile that the files look not too bad, with some tweaking and using Markdown syntax, we can make them look nice!

          Show
          Uwe Schindler added a comment - Attached a first patch to demonstate the idea. The patch adds a new <pegdown/> macro to common-build.xml that can convert any TXT file to a HTML representation (if the syntax is fine). It has some hacks: It uses the first line of the TXT file as HTML page title It converts the first line to a first level heading It rewrites LUCENE-xxx/SOLR-xxx identifiers to Markdown Links to JIRA The patch converts a few files (including CHANGES.txt!!!) to HTML using that macro and places them in build/docs, no linking at the moment. It is visile that the files look not too bad, with some tweaking and using Markdown syntax, we can make them look nice!
          Hide
          Uwe Schindler added a comment -
          Show
          Uwe Schindler added a comment - Pegdown: https://github.com/sirthias/pegdown

            People

            • Assignee:
              Uwe Schindler
              Reporter:
              Uwe Schindler
            • Votes:
              0 Vote for this issue
              Watchers:
              1 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Development