Edgewall Software
Modify

Opened 7 years ago

Closed 4 years ago

#12835 closed task (fixed)

Improve ReST export

Reported by: Ryan J Ollos Owned by: Ryan J Ollos
Priority: normal Milestone: 1.5.2
Component: general Version:
Severity: normal Keywords:
Cc: Branch:
Release Notes:
API Changes:
Internal Changes:

pypandoc is used to export TracInstall / TracUpgrade to INSTALL.rst / UPGRADE.rst, replacing html2rest. pypandoc works on Python 3 but html2rest does not.

Description (last modified by Ryan J Ollos)

Copied from 11914#comment:22:


Remained issues:

  • `mod_python`_ and `CGI`_ don't work. Link and italic markups cannot be nested in ReST.
  • One of `trac- admin`_ doesn't work due to wrapped the link.
  • `SilverCity`_ doesn't work.
  • ` [trac] htdocs_location`_ doesn't work.
  • Some Title level inconsistent:// errors.

Also:

  • Links to anchors in the document direct back to wiki trac.edgewall.org

Using pypandoc rather than html2rest fixes some of the title level inconsistencies, and other markup problems. It also appears to be well-maintained, whereas html2rest hasn't been updated since 2012.

Attachments (0)

Change History (17)

comment:1 by Ryan J Ollos, 7 years ago

Description: modified (diff)

comment:2 by Ryan J Ollos, 7 years ago

Milestone: 1.0.151.0.16

comment:3 by Ryan J Ollos, 7 years ago

It appears that html2rest is inserting ZWSPs (r16171):

@@ -106,15 +79,15 @@ See `<U+200B>DatabaseBackend`_ for details.
 For the MySQL database
 ``````````````````````

-Trac works well with MySQL, provided you follow the guidelines:
+Trac works well with MySQL, provided you use the following:


 + `<U+200B>MySQL`_, version 5.0 or later
-+ `<U+200B>MySQLdb`_, version 1.2.2 or later
++ `<U+200B>PyMySQL`_


 Given the caveats and known issues surrounding MySQL, read carefully
-the `<U+200B>MySqlDb*`_ page before creating the database.
+the `<U+200B>MySqlDb`_ page before creating the database.


 Optional Dependencies

comment:4 by Ryan J Ollos, 7 years ago

Milestone: 1.0.161.3.3

comment:5 by Ryan J Ollos, 7 years ago

Milestone: 1.3.31.4

in reply to:  3 comment:6 by Ryan J Ollos, 5 years ago

Replying to Ryan J Ollos:

It appears that html2rest is inserting ZWSPs (r16171):

Or failing to strip them out, rather.

See also: comment:2:ticket:13177.

comment:7 by Ryan J Ollos, 5 years ago

Committed variant of comment:2:ticket:13177 patch in r17001, updated INSTALL.rst and UPGRADE.rst in r17002.

comment:8 by Ryan J Ollos, 5 years ago

Description: modified (diff)

comment:9 by Ryan J Ollos, 5 years ago

Committed comment:5:ticket:13177 fix in r17075.

in reply to:  description comment:10 by Ryan J Ollos, 5 years ago

Release Notes: modified (diff)
Resolution: fixed
Status: assignedclosed

Replying to Ryan J Ollos:

Copied from 11914#comment:22:


Remained issues: …

Edited:

  • Links to anchors in the document direct back to wiki trac.edgewall.org

This might be worth the effort to fix someday.

Using pypandoc rather than html2rest fixes some of the title level inconsistencies, and other markup problems. It also appears to be well-maintained, whereas html2rest hasn't been updated since 2012.

Here are the changes I had worked on: log:rjollos.git:t12835_improve_rest_export

Documentation changes committed in r17085. I think this is enough improvement for 1.4.

Last edited 5 years ago by Ryan J Ollos (previous) (diff)

comment:11 by Ryan J Ollos, 4 years ago

Milestone: 1.41.5.2
Resolution: fixed
Status: closedreopened

wiki2rst.py modifies links to avoid duplicates by adding one or more * characters. The same could probably be done using a pandoc filter. However, it seems easier to just use anonymous inline links by not using the --reference-links option.

comment:12 by Ryan J Ollos, 4 years ago

Status: reopenedassigned

comment:13 by Ryan J Ollos, 4 years ago

Internal Changes: modified (diff)
Release Notes: modified (diff)

If no problems found, I'll commit [1fdae527/rjollos.git] and [4ebaefd6/rjollos.git] ahead of #12130.

comment:14 by Ryan J Ollos, 4 years ago

On the TracInstall page, [#DeployingTrac Deploying Trac] is formatted to HTML:

<a class="wiki" href="/wiki/TracInstall#DeployingTrac">Deploying Trac</a>

Shouldn't it just be?:

<a class="wiki" href="#DeployingTrac">Deploying Trac</a>
Last edited 4 years ago by Ryan J Ollos (previous) (diff)

comment:15 by Ryan J Ollos, 4 years ago

I plan to spend some more time on this, but here is work so far: log:rjollos.git:t12835_pandoc.

[8b56ee226/rjollos.git] addresses the issue I posted to the pandoc mailing list. The internal links work correctly when rendered with docutils, both in Trac brower and generated using:

rst2html5.py INSTALL.rst > INSTALL.html

comment:16 by Ryan J Ollos, 4 years ago

Proposed changes: log:rjollos.git:t12835_pandoc.1.

comment:17 by Ryan J Ollos, 4 years ago

Internal Changes: modified (diff)
Resolution: fixed
Status: assignedclosed

Committed to trunk in r17403.

Modify Ticket

Change Properties
Set your email in Preferences
Action
as closed The owner will remain Ryan J Ollos.
The resolution will be deleted. Next status will be 'reopened'.
to The owner will be changed from Ryan J Ollos to the specified user.

Add Comment


E-mail address and name can be saved in the Preferences .
 
Note: See TracTickets for help on using tickets.