memilanuk — 2010-06-07T17:03:11-04:00 — #1
I'm thinking about helping someone out with the documentation for a project he's working on... basically taking the half-dozen or so text files he wrote in Wordpad years ago and trying to turn them into something useful where the end user can navigate from a table of contents to a particular page, and then have the little 'Next' 'Previous' and 'Up' links on each page to facilitate getting around. I know enough about html/css I could probably make something work, but I thought it might be simpler to not reinvent the wheel if anybody here could point me in the right direction of any pre-existing templates along those lines?
memilanuk — 2010-06-11T20:11:34-04:00 — #2
Originally I had been thinking of something like a php template, that kept some of the 'active' stuff in a separate include file that would be called from the individual pages. Then I remembered there is no webserver or php involved here, so back to html/css.
Basic html with <a href> and <a name> tags seems to be working just fine. I'm having to do a bit of 'adaptation' of the material anyway. Later I'll try dressing it up a little bit with some CSS.
I'll take a look at the w3c stuff, thanks.
alexdawson — 2010-06-11T20:05:54-04:00 — #3
I don't think it really requires much in the way of a template, after all, most of those documents have very little in terms of style. If you know HTML and CSS you could pull something together very quickly. I'm particularly a fan of the W3C specifications (as to their official looking layout), though whatever you use you can use the existing sites code for inspiration. My advice would be produce something very basic (like just HTML) and style it up as you see fit.
memilanuk — 2010-06-11T19:58:20-04:00 — #4
What I had in mind was something more like the HOWTOs from tldp.org or the html manuals from mysql.org. The former uses some specific (but non-proprietary) markup software to make their stuff work; honestly it looks like yet another markup language to have to learn well enough to be half-ways proficient with so not interested. The latter is a bit bigger that what I probably have to cover (by several orders of magnitude) but its close enough to lift ideas from. The PDF thing... I keep pdf copies of some other documents for a non-profit organization; seems like I spend about as much time generating 'new' PDF copies of the document after some minor change somebody wanted after the 'last call'... and again... and again... etc. HTML - tell 'em to refresh their browser, done.
alexdawson — 2010-06-11T19:09:52-04:00 — #5
That's not much to go on, are these long documents? If we're talking lots of pages per document you might be better off converting them to PDF. While HTML and CSS would be able to have the document broken down, PDF files are pretty great for navigation, accessibility and allowing people to print and or store them offline for future reading. It's the generally accepted method on the web of showcasing long documents that may require redistribution.
alexdawson — 2010-06-11T20:55:02-04:00 — #6
Just for the record: A name="" is deprecated, these days there's a much more elegant solution, you still link to file.html#section in the href attribute but rather than attach an a name element to the section, you simply give the element you want it to jump too an ID which matches the fragment. So for example: rather than <a name="hello"><h2>Hello</h3></a> you would use <h2 id="hello">Hello</h2>... much better and it requires less bloated markup.