On 4/1/2016 7:14 PM, Warren Young wrote:
On Apr 1, 2016, at 7:13 PM, Warren Young <w...@etr-usa.com> wrote:
On Apr 1, 2016, at 6:50 PM, Ross Berteig <r...@cheshireeng.com>
wrote:
may I recommend just reading /test-all-help cover to cover once
in a while?
Okay. Back in a few… A few hours, that is. :)
Aaaand I’m back. :)
I found that page so helpful that I added a link to it from my Fossil
skin’s header. Recipe:
html "<a href='$home/test-all-help'>RefMan</a>\n”
Maybe this should be a standard feature?
I've done the same thing, or at least dropped the similar link into a
prominent place, in several project repos of mine.
If it were to become a standard feature, I think it likely should be
split into two major sections. One for the web face, and one for the
CLI. Their audiences are, I think, different kinds of users.
That said, for the task I foolishly just dove into, having them all in
one document is handy for proofreading and verifying consistency.
I’m not wild about the name RefMan. I just thought “Help” implied
something a bit more like a user manual than what this link provides,
which is basically a reference manual.
Yeah, this is a pretty bare reference to all commands and web pages. A
lot is left unsaid, or left to be inferred from the web of see also and
casual name dropping. Including some additional overview topics in the
compiled-in help would go a long way to softening some of the sharp edges.
It would be nice if there was a mode for the code that generates this
page to cause it to compress out the redundancy. That is, instead of
separate annotate, blame and praise sections, I’d prefer a variant of
this page that just listed the three aliases together, with a single
copy of the explanatory text.
The implementation of /test-all-help is probably only seven lines of
code, and simply spits out a section for each entry in the large array
built by mkindex. The order in the output is exactly the order in the
internal array. The new test-all-help command is very similar, except I
added some options to pick and choose chunks in ways that made sense to
me but likely aren't the best choice.
The fact that some commands are synonyms is almost entirely discarded by
mkindex, and would be difficult for the help system to notice right now.
(In effect, it would have to scan a table sorted by command name to find
commands that happen to have the same function pointer stored.) But I'm
sure if we had a mandate to make the help system more useful from the
web that some combination of improvements to mkindex, the supporting
data structures, and the page implementation could happen.
But, it’s quite useful as-is.
--
Ross Berteig r...@cheshireeng.com
Cheshire Engineering Corp. http://www.CheshireEng.com/
+1 626 303 1602
_______________________________________________
fossil-users mailing list
fossil-users@lists.fossil-scm.org
http://lists.fossil-scm.org:8080/cgi-bin/mailman/listinfo/fossil-users
