Conversion of docs to .rst #1225
Labels
No Label
0.2.0
0.3.0
0.4.0
0.5.0
0.5.1
0.6.0
0.6.1
0.7.0
0.8.0
0.9.0
1.0.0
1.1.0
1.10.0
1.10.1
1.10.2
1.10a2
1.11.0
1.12.0
1.12.1
1.13.0
1.14.0
1.15.0
1.15.1
1.2.0
1.3.0
1.4.1
1.5.0
1.6.0
1.6.1
1.7.0
1.7.1
1.7β
1.8.0
1.8.1
1.8.2
1.8.3
1.8β
1.9.0
1.9.0-s3branch
1.9.0a1
1.9.0a2
1.9.0b1
1.9.1
1.9.2
1.9.2a1
LeastAuthority.com automation
blocker
cannot reproduce
cloud-branch
code
code-dirnodes
code-encoding
code-frontend
code-frontend-cli
code-frontend-ftp-sftp
code-frontend-magic-folder
code-frontend-web
code-mutable
code-network
code-nodeadmin
code-peerselection
code-storage
contrib
critical
defect
dev-infrastructure
documentation
duplicate
enhancement
fixed
invalid
major
minor
n/a
normal
operational
packaging
somebody else's problem
supercritical
task
trivial
unknown
was already fixed
website
wontfix
worksforme
No Milestone
No Assignees
3 Participants
Notifications
Due Date
No due date set.
Reference: tahoe-lafs/trac-2024-07-25#1225
Loading…
Reference in New Issue
No description provided.
Delete Branch "%!s(<nil>)"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
As discussed on the mailing list, I'll be reformatting the docs in the source tree as reStructuredText.
Attachment stats.txt (14583 bytes) added
docs/stats.txt, converted t rST
I've just attached an example document (stats.txt) converted to rST format. Here's an HTML render of that file: http://p-static.net/stats.html
Attachment docs-txt-rst-conversion.patch (133862 bytes) added
Patch against latest darcs checkout
Just attached docs-txt-rst-conversion.patch, which has all the .txt files under docs/ converted to rST. Corrections and suggestions on the formatting are welcome.
I've also generated a set of html documents from the files, using rst2html.py. You can see the result here: http://p-static.net/tahoe-docs/
Seems like Trac has built-in support for .rst - http://trac.edgewall.org/wiki/WikiRestructuredText
With this, we wouldn't even need a separate conversion to html step - it looks like Trac will even render .rst in the source viewer directly, if we can figure out the darcs equivalent for setting a svn property.
Replying to p-static:
It sound fine for me.
Maybe we need to add the darc revision in bottom of file, so if you print, you can know from which revision is the file.
Like I did with my php script in bottom of file (just note that script is not finished and I need to reformat the revision output):configuration.txt
That'd be pretty useful. We could do it in the conversion script pretty easily by writing a text file with the version info (and whatever else we want in a footer?) and then using rST's include directive to pull that in. It'd tie us to using a conversion script, but that probably would have happened anyway.
Replying to p-static:
According to this post, darcs has no direct equivalent to svn properties. I don't know whether TracDarcs has any way to configure the mapping of filetypes to MIME types.
Attachment docs-txt-to-rst.darcs.patch (141348 bytes) added
renamed the files from .txt to .rst, fixed a formatting issue in backdoors.rst, added NEWS entry, added darcs patch description (commit log entry)
Brian: please review in order to check for any major documentation corruption before we commit this.
In changeset:8143183e39733786:
The files in source:docs/frontends have not been converted.
... and the other subdirectories, of which source:docs/specifications is probably most important.
p-static told me in email that he hopes to fix this in the next couple of days for the 1.8.1 release.
Just to keep folks updated on this: I'll be adding the work to a Github repo as it goes. When I'm done, I'll attach a complete patch to this issue.
http://github.com/p-static/tahoe-lafs
Attachment docs-txt-rst-conversion-ii.patch (454901 bytes) added
conversion of specifications/ and frontends/
Just attached the next part of the conversion; this patch covers the files in docs/specifications/ and docs/frontends/. (This corresponds to http://github.com/p-static/tahoe-lafs/commit/37b543fc5168437653ab0f1b867a9bff7ada721c) In case I don't finish in time for 1.8.1, this is a logical unit of work to add to it.
I renamed the files in this patch, not realizing that it would duplicate the contents of each file twice in the diff. >_< For the next one, I'll probably go back to leaving them named *.txt, and letting whoever applies the patch rename the files.
As for the rest of the conversion, the only remaining directories are historical/ and proposed/. I'm planning to finish proposed/ this weekend, but I'm wondering if we actually care about converting the historical docs. Anybody especially want to see them in rST format?
hm, if you're doing this in darcs, you might consider using two separate patches: the first would rename *.txt to *.rst, the second would make the actual rST changes to the contents. That might cause the tools to work better.
Or it might not, I'm not sure..
I think p-static's problem with the file contents appearing twice in each diff were from his use of git. When using darcs, you use
darcs mv
to rename the file and then you can record that mv along with the edits to the contents of the file in a single patch. Whoever commits this to trunk, please make sure it is an mv patch and not a patch that removes the old file and adds a new file!p-static's patch was applied in changeset:8143183e39733786. p-static: I agree that source:docs/historical can remain untouched, Did you update source:docs/proposed?
Oh, now I remember what happened. I started looking at proposed/, but then realized that most of the files there haven't been touched in a few years, so I didn't know what their status actually was. Then I completely forgot to update this bug, sorry about that D:
I think we can go ahead and mark this as resolved, unless some of those proposed specs are still active.
It seems like the second part of the patch (that converted frontends/ and specifications/) may not have been applied.
http://tahoe-lafs.org/source/tahoe-lafs/trunk/docs/frontends/
Oddly enough, Trac tries to redirect me to the .rst versions of the files, and then gives a 404. No idea what's going on there.
Replying to p-static:
I told apache (which is the front-end) to redirect:
In changeset:1d5c705201fdcf0e:
In changeset:7da1885531508c25:
Replying to david-sarah@…:
This was meant to refer to ticket:1277#comment:80537.
In changeset:458b2de08bb084e5:
In changeset:5d612c87abe71fdd:
In changeset:5ce5faf0af485eeb:
In changeset:341cad80ff30ffd2:
In changeset:5f73c27b23007ee4:
TODO: write things that look like URLs but aren't (e.g. the strport examples in http://tahoe-lafs.org/trac/tahoe-lafs/browser/trunk/docs/configuration.rst) in a way that stops them from being linkified.
In changeset:64a4ef5966d8f743:
In changeset:e35cbb7aef3728fb:
This is done, except for a NEWS entry. p-static's second patch was applied in changeset:2100273ce3436877.
In changeset:1190ce614303b6fb: