[thg-dev] TortoisHg Documentation

[Boggess, Rod]

A few questions about the documentation:



1) Nautilus scripts no longer work in Ubuntu 12.04 - even the PPA
for TortoiseHg-Nautilus generates errors. Are there plans to fix this? I
ask because I'm going to be documenting the context menu popups and I
want to know if I should mention that these only work in Explorer on
Windows (and not in Nautilus on Linux).

2) The only context help link available is on the Workbench which
correctly points to 5.4. Can someone add a context menu link to section
4.0 for the Explorer Context (popup) Menu? I believe it would be enough
to add one context menu help link, rather than a separate link on each
context menu popup dialog, but if someone wanted to go crazy, I could
ensure that a link existed for each of those, too.

3) I keep reading hints that Sphinx and Docutils can "extract
documentation out of my python code." Is this extraction the origin of
the source text files? In short, should I be looking inside of the
python code modules to update the doc comments inside of the code,
instead of updating the text files (which will be summarily overwritten
the next time someone extracts the comments from the python code)?

4) I saw a TODO list in the docs folder, and although I don't
really understand the tasks, should I be focusing my energies on
addressing those as priority issues before moving on to the expansion of
MQ, context menu, and workbench documentation?

5) Lastly, does anyone here have a recommendation for where I can
get the following question answered:

`Table of Contents`_ takes me to the ToC anchor in the current page.
:doc:`faq` takes me to the FAQ document in the set. But how do I combine
these two so I can go to a bookmark within another document in the set?
I want to generate the equivalent HTML 5 of a fragid within a relative
URL location. In other words, if I were in faq.html, and I wanted to
create a clickable anchor that took me to <h2 id='ToC'>Table of
Contents</h2> in the index.html page, I would use,

<a href="index.html#ToC">See Table of Contents</a> for more information.

How do I do the equivalent in restructured text? (I need to know how to
mark the fragid as well as how to reference the bookmark with #ToC.)

I'll continue to look
http://packages.python.org/an_example_pypi_project/sphinx.html#table-of-
contents, http://docutils.sourceforge.net/rst.html,
http://docutils.sourceforge.net/docs/user/rst/quickref.html, and
http://docutils.sourceforge.net/docs/user/rst/cheatsheet.txt, but it
would help a lot if I knew what to search for within these documents (or
in Google). I'm just too stupid to know what these bookmarks are called
in restructured text parlance.





Rod Boggess

Software Engineer

Tenova Core

Cherrington Corporate Center

100 Corporate Center Drive

Coraopolis, PA 15108

Phone: [phone] x2467

Email: ***@tenovacore.com

Website: www.tenovacore.com

[Boggess, Rod]

Let me preface my reply with, "I hate MS Outlook!" I found one partial
answer to my own questions.



A few questions about the documentation:



1) Nautilus scripts no longer work in Ubuntu 12.04 - even the PPA
for TortoiseHg-Nautilus generates errors. Are there plans to fix this? I
ask because I'm going to be documenting the context menu popups and I
want to know if I should mention that these only work in Explorer on
Windows (and not in Nautilus on Linux).

2) The only context help link available is on the Workbench which
correctly points to 5.4. Can someone add a context menu link to section
4.0 for the Explorer Context (popup) Menu? I believe it would be enough
to add one context menu help link, rather than a separate link on each
context menu popup dialog, but if someone wanted to go crazy, I could
ensure that a link existed for each of those, too.

It would appear that section 5.2 would be the correct choice for a
context menu help link.



3) I keep reading hints that Sphinx and Docutils can "extract
documentation out of my python code." Is this extraction the origin of
the source text files? In short, should I be looking inside of the
python code modules to update the doc comments inside of the code,
instead of updating the text files (which will be summarily overwritten
the next time someone extracts the comments from the python code)?

4) I saw a TODO list in the docs folder, and although I don't
really understand the tasks, should I be focusing my energies on
addressing those as priority issues before moving on to the expansion of
MQ, context menu, and workbench documentation?

5) Lastly, does anyone here have a recommendation for where I can
get the following question answered:

`Table of Contents`_ takes me to the ToC anchor in the current page.
:doc:`faq` takes me to the FAQ document in the set. But how do I combine
these two so I can go to a bookmark within another document in the set?
I want to generate the equivalent HTML 5 of a fragid within a relative
URL location. In other words, if I were in faq.html, and I wanted to
create a clickable anchor that took me to <h2 id='ToC'>Table of
Contents</h2> in the index.html page, I would use,

<a href="index.html#ToC">See Table of Contents</a> for more information.

How do I do the equivalent in restructured text? (I need to know how to
mark the fragid as well as how to reference the bookmark with #ToC.)

I'll continue to look
http://packages.python.org/an_example_pypi_project/sphinx.html#table-of-
contents, http://docutils.sourceforge.net/rst.html,
http://docutils.sourceforge.net/docs/user/rst/quickref.html, and
http://docutils.sourceforge.net/docs/user/rst/cheatsheet.txt, but it
would help a lot if I knew what to search for within these documents (or
in Google). I'm just too stupid to know what these bookmarks are called
in restructured text parlance.



And although I haven't figured out how these work in reST, I have
figured out that they're called targets. I just can't find any examples
of a target with an external link.

[Boggess, Rod]

In case anyone is following, here's my status...

A few questions about the documentation:

<snip>

1) Lastly, does anyone here have a recommendation for where I can
get the following question answered:

`Table of Contents`_ takes me to the ToC anchor in the current page.
:doc:`faq` takes me to the FAQ document in the set. But how do I combine
these two so I can go to a bookmark within another document in the set?
I want to generate the equivalent HTML 5 of a fragid within a relative
URL location. In other words, if I were in faq.html, and I wanted to
create a clickable anchor that took me to <h2 id='ToC'>Table of
Contents</h2> in the index.html page, I would use,

<a href="index.html#ToC">See Table of Contents</a> for more information.

How do I do the equivalent in restructured text? (I need to know how to
mark the fragid as well as how to reference the bookmark with #ToC.)

I'll continue to look
http://packages.python.org/an_example_pypi_project/sphinx.html#table-of-
contents, http://docutils.sourceforge.net/rst.html,
http://docutils.sourceforge.net/docs/user/rst/quickref.html, and
http://docutils.sourceforge.net/docs/user/rst/cheatsheet.txt, but it
would help a lot if I knew what to search for within these documents (or
in Google). I'm just too stupid to know what these bookmarks are called
in restructured text parlance.



The :ref: tag is supposed to work across source documents, but it
doesn't. I have not yet found a mailing list for Sphinx, but I did find
one for Docutils, and sent an email asking for clarification or
correction to my source to link a reference to another document page. I
haven't heard anything back.

[Steve Borho]

Sorry for the late replies

1) Nautilus scripts no longer work in Ubuntu 12.04 – even the PPA for
TortoiseHg-Nautilus generates errors. Are there plans to fix this? I ask
because I’m going to be documenting the context menu popups and I want to
know if I should mention that these only work in Explorer on Windows (and
not in Nautilus on Linux).

No one is maintaining the nautilus extension, I am tempted to remove
it until a maintainer appears, just to stop it from being packaged any
more.

2) The only context help link available is on the Workbench which
correctly points to 5.4. Can someone add a context menu link to section 4.0
for the Explorer Context (popup) Menu? I believe it would be enough to add
one context menu help link, rather than a separate link on each context menu
popup dialog, but if someone wanted to go crazy, I could ensure that a link
existed for each of those, too.

I think 5.2 would be a better link. I have a local patch which adds this.

3) I keep reading hints that Sphinx and Docutils can “extract
documentation out of my python code.” Is this extraction the origin of the
source text files? In short, should I be looking inside of the python code
modules to update the doc comments inside of the code, instead of updating
the text files (which will be summarily overwritten the next time someone
extracts the comments from the python code)?

No, we don't maintain any documentation within the Python code. This
would only be useful if TortoiseHg were being provided as a Python
library.

4) I saw a TODO list in the docs folder, and although I don’t really
understand the tasks, should I be focusing my energies on addressing those
as priority issues before moving on to the expansion of MQ, context menu,
and workbench documentation?

Work on whatever you like.

5) Lastly, does anyone here have a recommendation for where I can get
`Table of Contents`_ takes me to the ToC anchor in the current page.
:doc:`faq` takes me to the FAQ document in the set. But how do I combine
these two so I can go to a bookmark within another document in the set? I
want to generate the equivalent HTML 5 of a fragid within a relative URL
location. In other words, if I were in faq.html, and I wanted to create a
clickable anchor that took me to <h2 id=’ToC’>Table of Contents</h2> in the
index.html page, I would use,
<a href=”index.html#ToC”>See Table of Contents</a> for more information.
How do I do the equivalent in restructured text? (I need to know how to mark
the fragid as well as how to reference the bookmark with #ToC.)
I’ll continue to look
http://packages.python.org/an_example_pypi_project/sphinx.html#table-of-contents,
http://docutils.sourceforge.net/rst.html,
http://docutils.sourceforge.net/docs/user/rst/quickref.html, and
http://docutils.sourceforge.net/docs/user/rst/cheatsheet.txt, but it would
help a lot if I knew what to search for within these documents (or in
Google). I’m just too stupid to know what these bookmarks are called in
restructured text parlance.

I don't know if I ever found a reliable way to do this.

[Boggess, Rod]

I'm actually glad you took a while to answer some of these. I figured
out a bunch on my own, which is usually more memorable.

Post by Steve Borho
Sorry for the late replies

Post by Boggess, Rod
1) Nautilus scripts no longer work in Ubuntu 12.04 - even the

PPA for

Post by Steve Borho

Post by Boggess, Rod
TortoiseHg-Nautilus generates errors. Are there plans to fix this? I
ask because I'm going to be documenting the context menu popups and I
want to know if I should mention that these only work in Explorer on
Windows (and not in Nautilus on Linux).

No one is maintaining the nautilus extension, I am tempted to remove

it until

Post by Steve Borho
a maintainer appears, just to stop it from being packaged any more.

Thanks. I found some alternate scripts Nautilus scripts, but I removed
them. The only thing I really miss are the icon overlays, and the
scripts didn't restore that function, they just opened a context menu.
If I run across them again, I'll see if I can contact the creator to see
if he's interested in having a poke at the thg version of the scripts.

Post by Steve Borho

Post by Boggess, Rod
2) The only context help link available is on the Workbench which
correctly points to 5.4. Can someone add a context menu link to
section 4.0 for the Explorer Context (popup) Menu? I believe it

would

Post by Steve Borho

Post by Boggess, Rod
be enough to add one context menu help link, rather than a separate
link on each context menu popup dialog, but if someone wanted to go
crazy, I could ensure that a link existed for each of those, too.

I think 5.2 would be a better link. I have a local patch which adds this.

I really didn't want to get into coding on this, if I can avoid it.
Since this isn't the OP's issue, I'll leave this alone, but I agree that
a Help link to 5.2 would be fantastic. Since the link isn't required to
fix the documents, I'll focus on that for now and rethink getting into
the code later.

Post by Steve Borho

Post by Boggess, Rod
5) Lastly, does anyone here have a recommendation for where I can get
`Table of Contents`_ takes me to the ToC anchor in the current page.
:doc:`faq` takes me to the FAQ document in the set. But how do I
combine these two so I can go to a bookmark within another document

in

Post by Steve Borho

Post by Boggess, Rod
the set? I want to generate the equivalent HTML 5 of a fragid within

a

Post by Steve Borho

Post by Boggess, Rod
relative URL location. In other words, if I were in faq.html, and I
wanted to create a clickable anchor that took me to <h2

id='ToC'>Table

Post by Steve Borho

Post by Boggess, Rod
of Contents</h2> in the index.html page, I would use,
<a href="index.html#ToC">See Table of Contents</a> for more

information.

Post by Boggess, Rod
How do I do the equivalent in restructured text? (I need to know how
to mark the fragid as well as how to reference the bookmark with
#ToC.)
I'll continue to look

http://packages.python.org/an_example_pypi_project/sphinx.html#table-o

Post by Boggess, Rod
f-contents, http://docutils.sourceforge.net/rst.html,
http://docutils.sourceforge.net/docs/user/rst/quickref.html, and
http://docutils.sourceforge.net/docs/user/rst/cheatsheet.txt, but it
would help a lot if I knew what to search for within these documents
(or in Google). I'm just too stupid to know what these bookmarks are
called in restructured text parlance.

I don't know if I ever found a reliable way to do this.

I figured this out in a moment of Doh! The labeled references are the
only way to make the links work across documents within the set. Outside
references are more problematic in that they have to be maintained to
avoid dead links. I can take on that role for a while.

Thanks again for your help and insights. I have a lot to think about.
Now that I've gotten one patch in, I can move from document to document
in the source and hopefully bring things up to date. I need to play
around some with the context menus because there are a lot more versions
of the context menus than are shown in the images.