Conversion of docs to .rst #1225

Closed
opened 2010-10-13 05:26:17 +00:00 by p-static · 36 comments
p-static commented 2010-10-13 05:26:17 +00:00
Owner

As discussed on the mailing list, I'll be reformatting the docs in the source tree as reStructuredText.

As discussed on the mailing list, I'll be reformatting the docs in the source tree as reStructuredText.
tahoe-lafs added the
documentation
minor
enhancement
n/a
labels 2010-10-13 05:26:17 +00:00
tahoe-lafs added this to the soon milestone 2010-10-13 05:26:17 +00:00
p-static commented 2010-10-13 06:30:35 +00:00
Author
Owner

Attachment stats.txt (14583 bytes) added

docs/stats.txt, converted t rST

**Attachment** stats.txt (14583 bytes) added docs/stats.txt, converted t rST
p-static commented 2010-10-13 06:31:32 +00:00
Author
Owner

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

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>
p-static commented 2010-10-14 07:49:17 +00:00
Author
Owner

Attachment docs-txt-rst-conversion.patch (133862 bytes) added

Patch against latest darcs checkout

**Attachment** docs-txt-rst-conversion.patch (133862 bytes) added Patch against latest darcs checkout
p-static commented 2010-10-14 07:55:54 +00:00
Author
Owner

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/

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/>
p-static commented 2010-10-14 17:21:12 +00:00
Author
Owner

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.

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.
freestorm commented 2010-10-14 21:38:17 +00:00
Author
Owner

Replying to p-static:

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/

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

Replying to [p-static](/tahoe-lafs/trac-2024-07-25/issues/1225#issuecomment-80536): > 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/> 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](http://fred.submusic.ch/docformat/?url=http://tahoe-lafs.org/trac/tahoe-lafs/browser/trunk/docs/configuration.txt)
p-static commented 2010-10-15 02:16:21 +00:00
Author
Owner

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.

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.
davidsarah commented 2010-10-15 03:29:58 +00:00
Author
Owner

Replying to p-static:

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.

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.

Replying to [p-static](/tahoe-lafs/trac-2024-07-25/issues/1225#issuecomment-80537): > 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. According to [this post](@@http://www.mail-archive.com/darcs-users@darcs.net/msg09951.html@@), darcs has no direct equivalent to svn properties. I don't know whether [TracDarcs](http://darcs.arstecnica.it/trac-darcs/) 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)

**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.

Brian: please review in order to check for any major documentation corruption before we commit this.
zooko@zooko.com commented 2010-10-15 05:51:31 +00:00
Author
Owner

In changeset:8143183e39733786:

docs: convert all .txt docs to .rst thanks to Ravi Pinjala
fixes #1225
In changeset:8143183e39733786: ``` docs: convert all .txt docs to .rst thanks to Ravi Pinjala fixes #1225 ```
tahoe-lafs added the
fixed
label 2010-10-15 05:51:31 +00:00
davidsarah commented 2010-10-23 04:33:16 +00:00
Author
Owner

The files in source:docs/frontends have not been converted.

The files in source:docs/frontends have not been converted.
tahoe-lafs removed the
fixed
label 2010-10-23 04:33:16 +00:00
davidsarah commented 2010-10-23 04:34:54 +00:00
Author
Owner

... and the other subdirectories, of which source:docs/specifications is probably most important.

... 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.

p-static told me in email that he hopes to fix this in the next couple of days for the 1.8.1 release.
p-static commented 2010-10-29 03:18:21 +00:00
Author
Owner

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

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>
p-static commented 2010-10-29 05:45:43 +00:00
Author
Owner

Attachment docs-txt-rst-conversion-ii.patch (454901 bytes) added

conversion of specifications/ and frontends/

**Attachment** docs-txt-rst-conversion-ii.patch (454901 bytes) added conversion of specifications/ and frontends/
p-static commented 2010-10-29 05:50:53 +00:00
Author
Owner

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?

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..

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!

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?

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?
zooko modified the milestone from soon to 1.8.1 2010-11-18 06:43:13 +00:00
p-static commented 2010-11-18 07:06:51 +00:00
Author
Owner

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.

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.
zooko added the
fixed
label 2010-11-18 07:52:54 +00:00
zooko closed this issue 2010-11-18 07:52:54 +00:00
p-static commented 2010-12-04 08:22:48 +00:00
Author
Owner

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.

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.
tahoe-lafs removed the
fixed
label 2010-12-04 08:22:48 +00:00

Replying to p-static:

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.

I told apache (which is the front-end) to redirect:

    # make 301 /trac/tahoe -> /trac/tahoe-lafs
    RedirectMatch permanent ^/trac/tahoe$ http://tahoe-lafs.org/trac/tahoe-lafs
    RedirectMatch permanent ^/trac/tahoe/(.*) http://tahoe-lafs.org/trac/tahoe-lafs/$1

    # make a bare http://tahoe-lafs.org send users to the Tahoe trac instance
    RedirectMatch permanent ^/$ http://tahoe-lafs.org/trac/tahoe-lafs

    # 302 all .txt to .rst in the source tree
    # e.g. http://tahoe-lafs.org/source/tahoe-lafs/trunk/docs/known_issues.txt
    RedirectMatch permanent ^/source/tahoe-lafs/(.*).txt http://tahoe-lafs.org/source/tahoe-lafs/$1.rst
Replying to [p-static](/tahoe-lafs/trac-2024-07-25/issues/1225#issuecomment-80559): > 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. I told apache (which is the front-end) to redirect: ``` # make 301 /trac/tahoe -> /trac/tahoe-lafs RedirectMatch permanent ^/trac/tahoe$ http://tahoe-lafs.org/trac/tahoe-lafs RedirectMatch permanent ^/trac/tahoe/(.*) http://tahoe-lafs.org/trac/tahoe-lafs/$1 # make a bare http://tahoe-lafs.org send users to the Tahoe trac instance RedirectMatch permanent ^/$ http://tahoe-lafs.org/trac/tahoe-lafs # 302 all .txt to .rst in the source tree # e.g. http://tahoe-lafs.org/source/tahoe-lafs/trunk/docs/known_issues.txt RedirectMatch permanent ^/source/tahoe-lafs/(.*).txt http://tahoe-lafs.org/source/tahoe-lafs/$1.rst ```
david-sarah@jacaranda.org commented 2010-12-12 01:33:49 +00:00
Author
Owner

In changeset:1d5c705201fdcf0e:

Move .txt files in docs/frontends and docs/specifications to .rst. refs #1225
In changeset:1d5c705201fdcf0e: ``` Move .txt files in docs/frontends and docs/specifications to .rst. refs #1225 ```
david-sarah@jacaranda.org commented 2010-12-12 01:44:22 +00:00
Author
Owner

In changeset:7da1885531508c25:

docs/specifications/mutable.rst: correct the magic string for v1 mutable containers. refs #1225
In changeset:7da1885531508c25: ``` docs/specifications/mutable.rst: correct the magic string for v1 mutable containers. refs #1225 ```
davidsarah commented 2010-12-12 01:52:32 +00:00
Author
Owner

Replying to david-sarah@…:

In changeset:7da1885531508c25:

#CommitTicketReference repository="trunk" revision="4869"
docs/specifications/mutable.rst: correct the magic string for v1 mutable containers. refs #1225

This was meant to refer to ticket:1277#comment:80537.

Replying to [david-sarah@…](/tahoe-lafs/trac-2024-07-25/issues/1225#issuecomment-80564): > In changeset:7da1885531508c25: > ``` > #CommitTicketReference repository="trunk" revision="4869" > docs/specifications/mutable.rst: correct the magic string for v1 mutable containers. refs #1225 > ``` This was meant to refer to ticket:1277#[comment:80537](/tahoe-lafs/trac-2024-07-25/issues/1225#issuecomment-80537).
david-sarah@jacaranda.org commented 2010-12-12 01:58:07 +00:00
Author
Owner

In changeset:458b2de08bb084e5:

docs/specifications/dirnodes.rst: fix references to mutable.rst. refs #1225
In changeset:458b2de08bb084e5: ``` docs/specifications/dirnodes.rst: fix references to mutable.rst. refs #1225 ```
david-sarah@jacaranda.org commented 2010-12-12 05:48:01 +00:00
Author
Owner

In changeset:5d612c87abe71fdd:

Update hyperlinks between docs, and linkify some external references. refs #1225
In changeset:5d612c87abe71fdd: ``` Update hyperlinks between docs, and linkify some external references. refs #1225 ```
david-sarah@jacaranda.org commented 2010-12-12 05:57:13 +00:00
Author
Owner

In changeset:5ce5faf0af485eeb:

More specific hyperlink to architecture.rst from helper.rst. refs #1225
In changeset:5ce5faf0af485eeb: ``` More specific hyperlink to architecture.rst from helper.rst. refs #1225 ```
david-sarah@jacaranda.org commented 2010-12-12 06:05:41 +00:00
Author
Owner

In changeset:341cad80ff30ffd2:

Fix a link from webapi.rst to FTP-and-SFTP.rst. refs #1225
In changeset:341cad80ff30ffd2: ``` Fix a link from webapi.rst to FTP-and-SFTP.rst. refs #1225 ```
david-sarah@jacaranda.org commented 2010-12-12 06:19:02 +00:00
Author
Owner

In changeset:5f73c27b23007ee4:

Fix a link from uri.rst to dirnodes.rst. refs #1225
In changeset:5f73c27b23007ee4: ``` Fix a link from uri.rst to dirnodes.rst. refs #1225 ```
davidsarah commented 2010-12-12 06:42:15 +00:00
Author
Owner

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.

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.
david-sarah@jacaranda.org commented 2010-12-12 06:54:36 +00:00
Author
Owner

In changeset:64a4ef5966d8f743:

docs/known_issues.rst: fix an external link. refs #1225
In changeset:64a4ef5966d8f743: ``` docs/known_issues.rst: fix an external link. refs #1225 ```
david-sarah@jacaranda.org commented 2010-12-12 07:01:05 +00:00
Author
Owner

In changeset:e35cbb7aef3728fb:

docs/known_issues.rst: fix title and linkify another URL. refs #1225
In changeset:e35cbb7aef3728fb: ``` docs/known_issues.rst: fix title and linkify another URL. refs #1225 ```
davidsarah commented 2010-12-31 22:15:21 +00:00
Author
Owner

This is done, except for a NEWS entry. p-static's second patch was applied in changeset:2100273ce3436877.

This is done, except for a NEWS entry. p-static's second patch was applied in changeset:2100273ce3436877.
tahoe-lafs added
1.8.0
and removed
n/a
labels 2010-12-31 22:15:44 +00:00
david-sarah@jacaranda.org commented 2011-01-06 01:28:43 +00:00
Author
Owner

In changeset:1190ce614303b6fb:

NEWS: 'top' for node processes, WUI formatting, removal of GUI apps, documentation updates, foolscap dependency. refs #174, #1219, #1225
In changeset:1190ce614303b6fb: ``` NEWS: 'top' for node processes, WUI formatting, removal of GUI apps, documentation updates, foolscap dependency. refs #174, #1219, #1225 ```
warner modified the milestone from 1.8.1 to soon 2011-01-06 21:21:26 +00:00
tahoe-lafs added the
fixed
label 2011-01-06 23:49:10 +00:00
tahoe-lafs modified the milestone from soon to 1.8.2 2011-01-06 23:49:10 +00:00
Sign in to join this conversation.
No Milestone
No Assignees
3 Participants
Notifications
Due Date
The due date is invalid or out of range. Please use the format 'yyyy-mm-dd'.

No due date set.

Reference: tahoe-lafs/trac-2024-07-25#1225
No description provided.