Trac wiki migration, improve markup conversion code

[soehms]

A. According to the sage-devel thread of the same title, the following tasks must be completed:

1. • Create links with URLs of Trac tickets (to be removed after the migration of the tickets).
     Addressed in PR Add links to Trac tickets for the wiki migration #15.
2. • Add table alignment instructions.
     Addressed in PR Add table alignment instructions #16.
3. • Sections with fragment names
     Example: == Legacy sage-trac Account Request == #legacy-account-request following section Account Names Mapped to Real Names in Home.md. Addressed in PR Fix for item A.3. of issue #18 #21.
4. • Various bad links
     Examples: PageOutline and https://groups.google.com/forum/#!forum/sage-packaging in Distribution page. Addressed in PR Fix for items 4 and 7 and completion of item 5 of issue #18 #19.
5. • Various missing links
     Examples: [wiki:symbolics/maxima] and [https://en.wikipedia.org/wiki/Symbolic_computation] on Symbolics page
     Addressed in PR Add missing links #17
6. • Lines containing nested bullets are not converted.
     Examples: Missing Trac ticket links in nested bullets after abs_integrate on Symbolics page. Addressed in PR Fix for item A6 and A8 of issue #18 #23.
7. • Non working queries to the Trac ticket database.
     Examples: [query:?status=needs_review... on Symbolics page. Addessed in PR Fix for items 4 and 7 and completion of item 5 of issue #18 #19.
8. • First lines and headings of pages are omitted.
     Examples: Distribution page (heading is - Distribution and packaging of SageMath -). Infrastructure page (first line is This page aims to keep information public about Sage's infrastructure.)
     Addressed in PR Fix for item A6 and A8 of issue #18 #23.
9. • Global references (by URL) to Trac tickets should be localized in order to be converted more easily to their corresponding GitHub issue after ticket migration.
     Examples: Reference to ticket 25206 on Cygwin64port page. Addressed in PR Fix for items 4 and 7 and completion of item 5 of issue #18 #19.

B. Tasks to be performed manually after wiki migration:

1. • Replace explanations and references to the Trac wiki syntax with explanations and references to the GitHub wiki syntax.
     Examples: Reporting a bug

C. Tasks to be done after successful ticket migration:

1. • Remove the link to the Trac ticket so that they point to the corresponding GitHub issue.
2. • Replace requests to the Trac database with requests to GitHub issues (where possible). But maybe it's better to keep the queries on Trac and add corresponding queries on GitHub.
3. • Find analogues to Trac macros and insert them at the corresponding hints produced be the script in the new GitHub wiki.

[soehms]

Remarks

Concerning A. 3.

The script doesn't recognize headings that have an anchor (#legacy-account-request) in the definition. Should we just ignore these anchors? Apparently, GitHub Markdown defines anchors automatically to each heading. A link to the above anchor would look like [#legacy-account-request Legacy sage-trac Account Request] in the Trac wiki (but in this case it is not even used) and would work as [Legacy sage-trac Account Request](#legacy-account-request) in GitHub Markdown, as well. So it should be sufficient to implement the latter conversion.

Concerning A. 4.

Unfortunately Trac uses the syntax [[Name]] with two meanings. The first meaning is a relative link in the wiki. The second meaning is a macro that implements a plugin to the wiki page. The PageOutline macro creates the table of contents plugin for the current page. It seems that the only way to distinguish between these two meanings is to check the name against a corresponding list, which must be created before starting the migration.

The next question is: what to do with the macros? Do you just ignore? Or do they have useful replacements in GitHub? Perhaps we can turn them into links to the appropriate Trac documentation for now.

Concerning A. 6.

This is caused by the following line in trac2markdown of migration.py:

        if not line.startswith('    '):

I have no idea about the purpose of this line. Removing it would fix 6 and the second example of item 4. Furthermore, the lines

    text = re.sub(r'^             * ', r'****', text)
    text = re.sub(r'^         * ', r'***', text)
    text = re.sub(r'^     * ', r'**', text)
    text = re.sub(r'^ * ', r'*', text)

don't seem to make any changes:

>>> text
'abs_integrate`-related errors (see #12731 for possibly disabling or raising warning always with it)\n     * #13097 - integral of ln(1+4/5*sin(x))\n     * #11590 - `sgn()` fu'
>>> re.sub(r'^     * ', r'**', text3)
'abs_integrate`-related errors (see #12731 for possibly disabling or raising warning always with it)\n     * #13097 - integral of ln(1+4/5*sin(x))\n     * #11590 - `sgn()` fu'

If it were, the result would be even worse since "**" is not Markdown syntax for nested bullets. Does anyone have any idea what the purpose of these lines could be? I tend to remove them as well as they just create confusion.

Concerning A. 8.

This is due to the boolean multilines passed as True to the trac2markdown function when called from convert_wiki. Setting this boolean to False fixes the problem.

Concerning B. 1.

There is a lot of text explaining the functionality of the Trac syntax. Do we want to migrate that too? A lot of wiki pages are all about that (I think most pages that have Trac or Wiki in their names). For example there are a couple of WikiProzessors that are not just syntax highlighting and that have no equivalent in Markdown (e.g. #!td, see also the macros mentioned concerning 4).

[kwankyu]

Where is the final destination of the migrated wiki? That is, what is the repository that the migrated wiki will be placed?

Unlike migration of trac tickets, I think we can migrate trac wiki pages one by one, so that we fix some broken things manually on the migrated wiki pages, instead of perfecting the migration script and make one shot migration. Perhaps we should do both (fixing manually and improving the script).

If the plan is to keep trac running in read-only mode, then we may do the wiki migration gradually, independent of trac tickets migration.

What is the plan?

[kwankyu]

I guess the final destigation is sage.wiki. Who will have the write permission to the wiki? As a wiki, every developer should have the write permission. Is this possible?

[soehms]

Where is the final destination of the migrated wiki? That is, what is the repository that the migrated wiki will be placed?

I assume it to be https://github.com/sagemath/sage/wiki.

... Perhaps we should do both (fixing manually and improving the script).

Yes, I think so. Improving the script helps also for the ticket migration since surely there are references to wiki pages using all possible syntax variations, as well.

What is the plan?

From the migration document it is not completely clear. I think, we should consider the Wiki migration as a test case for the ticket migration and thus it should be completed before. For the procedure of the Wiki migration I have the following in mind:

1. Improve the script as long as there are obvious issues that can be fixed easily. Maybe we should create a list of pages that can be completely skipped. For example all pages that explain Trac functionality (having Trac or Wiki in their names).
2. Run the migration and merge the result into https://github.com/sagemath/trac_to_gh/wiki
3. Let the community check the result.
4. If there are still issues to be fixed generically go back to 1.
5. Do the remaining things manually. At least with respect of item B.1. there is still a good deal of manual work left to replace Trac-functionality specific explanations with appropriate links to the GitHub markdown documentation.
6. Let the community check the result again.
7. If there are still issues to be fixed manually go back to 5.
8. Move the result to it's final destination.

After that ticket migration might happen into an appropriate temporary repository at which the community can have a look at it. An iteration similar to 1.-4. can follow.

[soehms]

I guess the final destigation is sage.wiki. Who will have the write permission to the wiki? As a wiki, every developer should have the write permission.

In principal I agree! On the other hand reviews would improve the quality (but consumes resources).

Is this possible?

See this page.

[kwankyu]

Thanks. All you said sounds reasonable.

Are all the items in A of your first comment "obvious issues that can be fixed easily"? Or any of them is hard to fix but should be implemented because we cannot do it manually (that is hard to do manually)?

[soehms]

Are all the items in A of your first comment "obvious issues that can be fixed easily"? Or any of them is hard to fix but should be implemented because we cannot do it manually (that is hard to do manually)?

I think the hardest are done ore addressed, now. What remains are issues caused be some unreasonable lines of code. Deactivating these lines wil fix them. It's just a matter of understanding the purpose of them (see the corresponding remarks in the second comment).

[kwankyu]

Okay. I will see if I can help you with some easy items.

[kwankyu]

I am working on A.9. You want to convert, for instance, https://trac.sagemath.org/ticket/25206 to #25206. Right? And these #... will be converted to github issues later. Right?

[kwankyu]

I worry that my intervention may make things screwed up. Just let me know when you need a hand on any item.

[soehms]

I am working on A.9. You want to convert, for instance, https://trac.sagemath.org/ticket/25206 to #25206. Right? And these #... will be converted to github issues later. Right?

Both answers: Yes!

[soehms]

I worry that my intervention may make things screwed up. Just let me know when you need a hand on any item.

No problem! That can be treated in the PRs. The more people involved the better.