Please Help! We need instructions for creating a table of contents

[Jeremy Ruston]

We've had lots of feedback that suggests that people are struggling to use the existing docs to discover how to add a sidebar tab containing a table of contents, and how to get entries into the table of contents.

I'd very much appreciate a documentation contribution on this - has anyone already worked on this topic?

Many thanks

Jeremy

--

Jeremy Ruston
mailto:jeremy...@gmail.com

[Stephen Kimmel]

This may do. http://toc-tutorial.tiddlyspot.com/

Note that there is one aspect of this that I didn't cover, the the entries is the right order. In this case it didn't matter since I configured it to be alphabetical anyway. Still, I am doing something wrong with my own because I always get it alphabetically regardless of what I enter.

This still has a lot of room for improvement like being consistent in how it handles names for example. Comments are welcome.

[Jeremy Ruston]

Great work, Stephan, apologies for the delay in replying.

It works well, clean and easy to follow. The immediate issue is the use of screenshots, which raises some editorial and technical issues:

* Including images in one guide is going to set the expectation that screenshots will be provided consistently for all guide material. That's fine, it'll just take us a while to update the other docs. But it does mean that if we include images here then I think we're making a commitment to include images in other guide material in the future

* Using screenshots sets up a dependency on the core. If we, for example, implemented Mat's suggestions for an improved edit template, then someone would have to go through an awful lot of screenshots and remake them where required

* If we're going to include screenshots as external images, then we need to provide an easy means for users to download an offline copy of the docs including the images - ideally, by offering a ZIP file of them.

* I'd prefer to deliver screenshots in a consistent format as compressed PNGs. The screenshots in your examples are JPGs, leading to visual artefacts around some of the high contrast borders. Services like https://tinypng.com/ do a good job of crunching PNGS; screenshots compress particularly well.

I do think that the screenshots are very effective, but I am worried that they may open a can of worms.

Best wishes

Jeremy.

--
To post: TiddlyW...@googlegroups.com
To unsubscribe: TiddlyWikiDoc...@googlegroups.com
More info: http://groups.google.com/group/tiddlywikidocs?hl=en
Visit the wiki at: http://wiki.tiddlywiki.org
---
You received this message because you are subscribed to the Google Groups "TiddlyWikiDocs" group.
To unsubscribe from this group and stop receiving emails from it, send an email to tiddlywikidoc...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Tobias Beer]

Hi Jeremy,

 

I do think that the screenshots are very effective, but I am worried that they may open a can of worms.

I really think some $highlight widget will be much more efficient than screenshots in the long run

• scroll to a desired element
• have it flash a little / highlighted
• (optionally) display a popup with a message alongside it
• click to close or use to go to the next step, etc...

There would perhaps have to be some smarts about it for things that need clicking before a user gets to it, e.g. toolbar > more. Not sure how such a highlight-trail could be followed.

Best wishes, Tobias.

[Stephen Kimmel]

No need to apologize, Jeremy. You have a lot of things happening so response to every forum posting is not expected.

For me, the key issue is to "Show and Tell" the user what to do is far more effective than simply "Telling." You know the old saying, "A picture is worth a thousand words." I have spent far to much time trying to explain to people where something is on their screen. Just how to "Show" is a question for serious discussion.

Let's start with the last point. I'm not committed to the jpeg format; just more familiar with it. Compressed png files are fine with me.

There is a key question which we've been implying but avoiding: How many screen shots are we talking about? One hundred? One thousand? In how many documents? Fifty? Ten? I have no idea. How big the effort and the commitment depends on the answer to that question. If we could treat the shots like tiddlers and reuse and combine them as necessary, the number could still be manageable and the load on the server might be so bad if we used external images.

I like Tobias's suggestion of highlighting on the screen but my fear is that could be a programming nightmare. Drawing a flashing rectangle at a particular location on the screen should be simple enough but how do we make sure the rectangle is in the right place after someone has adjusted the screen layout? If someone has hidden part of what we need, what happens? We could adjust the CSS of a particular element to highlight the item but that would also require having an addressable element for each item we want to highlight. And a commitment to either rework that with each change that impacts that element. I'm not a good enough programmer in these languages to know how difficult the task will be so I'll defer that judgement to others.

The ultimate question to the use of screenshots is whether there is an equally effective way to accomplish the task without using them. If Tobias's suggestion is feasible then we can carry on using the screen shots as a stop gap until the widget is fully functional. If not, then what will we use?

[Jeremy Ruston]

> There is a key question which we've been implying but avoiding: How many screen shots are we talking about? One hundred? One thousand?

One possibility is to programmatically generate the screenshots on the command line. We can do this using Phantom.js, a library that renders a web page as a bitmap. We can write "screenshot" definitions consisting of tiddler values to be overlaid on a basic demo edition (content and state tiddlers), along with the position of the output rectangle.

Then we'd be able to generate the screenshots in different languages (!), and easily regenerate them when eg standard icons are changed.

Anyhow, the nub is that we can't start bringing in screenshots without laying down some infrastructure, and I don't think we can do that without breaking the moratorium. So we're back to trying the best we can accomplish with the tools at hand.

Best wishes

Jeremy.

Best wishes

Jeremy.

--

To post: TiddlyW...@googlegroups.com
To unsubscribe: TiddlyWikiDoc...@googlegroups.com
More info: http://groups.google.com/group/tiddlywikidocs?hl=en
Visit the wiki at: http://wiki.tiddlywiki.org
---
You received this message because you are subscribed to the Google Groups "TiddlyWikiDocs" group.
To unsubscribe from this group and stop receiving emails from it, send an email to tiddlywikidoc...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[barro...@gmail.com]

Just a suggestion for an alternate to screenshots.  I figure if I keep my peace cause I may not know enough to weigh in, I could be hoarding potential ideas.  Same can of worms-- extra work and raising of expectations.  Plus it may not be practical for all cases.  In the help pages I have done for my customized TW's for others, I have transcluded into the "help" tiddler, portions of TW's structure (using the appropriate snippets of format code from the wiki with any functions disabled) or created a mock-up with html element like bordered div's of the structure I wanted to illustrate.  In this case you would have a mock sidebar, single tab, with the table of contents being explained as its being built by instruction-- all using TW's code for ToC.  I believe that could actually be made a working ToC in the tiddler than would adjust to the instructions being detailed.

*  for identifying/ explaining the tiddler edit toolbar, I actually showed it in the help tiddler using a snippet I found in TW

** for a constructed mock-up, I made a mock-up of the entire wiki layout and transcribe in some of the default icons, very same icons the wiki uses then added notes inside the mockupnext to element-- ame could be done with button tooltips and links to more detailed helptiddlers

[Jeremy Ruston]

Hi Barrowgloom

Congratulations on the expert thread sleuthing! My reply above prefigures the innerwiki plugin. Funny how long these things can bounce around in ones brain before getting around to actually doing them!

As to your point here, yes, we can absolutely build miniature replicas of TW features without using iframes. Part of the attraction of the iframe technique is that it works so well for server side rendering (now done with Puppeteer rather than PhantomJS, but the principle is the same).

Best wishes

Jeremy

--

Jeremy Ruston

jer...@jermolene.com

https://jermolene.com

--

[barro...@gmail.com]

Thank you.  Yes, the ideas not only rattle around but snowball (ie spur even more)-- all when you're busy trying to do something else.  TW has really helped with that-- when the ideas come I put em in a new temp tiddler, tag em so they end up where their topic is and later go collect them up and add them to permanent tiddlers.

I'm not fully familiar with server side procedures but I have heard of the innerwiki plugin which got my attention.  I went with rendering inside the user instruction tiddlers to keep everything convenient in one place so not to lose the potential users' attention and interest.   More advanced instructions would be linked to existing official wiki documentation.  I'm all about taking advantage of what already exists.  Why I'm re-examining what I do to make sure I'm not duplicating things that may have already been done.  Stephen's documentation on ToC's will still work without the screenshots, perhaps with some flushing out to make up for the lack of screenshots?

[barro...@gmail.com]

This is belated but I've been busy playing Dr Frankenstein with TW << >>

This corncerns alternatives to screenshots for graphic representation of the wiki or portions of its layout.

Several suggestions based off what I have used for graphic representations of layouts, such as TW's overall layout.  The attached image shows the suggestions graphically and the attached .tid shows the TW layout diagram in a tiddler.  These could also be applied to flowcharts.

Keep in mind I don't know the programming side of things so I don't know of constraints/complications when it comes to the core and the software's inner workings.

Tables-- yes the frowned upon practice of using such for layouts.  Using border styling.  Svg's can used with this method, such as TW's core icons transcluded into it.
Div's/Div's (using display:table,row,cell).  Using border styling.  Much more flexible than tables but could get complex.  Svg's can used with this method, such as TW's core icons transcluded into it.
SVG-- Can stay relatively compact, used embedded, transcluded or external. Elements in the svg can have links to tiddlers holding further info (that could be revealed in the same tiddlers that has the svg)