HiPhish wrote:Zini wrote:...
OK, I have updated it with your suggestions. I have also changed the two/three tutorial chapters into one chapter called "tour" with two/three sections. That should make it clear that the tutorials are only an introduction.
Antsan wrote:...
Navigation should be no problem, you can do document-internal hyperlinks in reStructuredText, those can be implemented in the HTML or PDF output.
I know that, I am just confused about the reasoning behind making tutorials wikis and the manual/reference a book. If both have document-internal hyperlinks, there isn't that much of a difference either way, especially since there is no reason to put different topics in the manual into a specific order.
About LaTeX, it's a nice system if you are content with the defaults and it's the most useful for mathematicians. For anything else you will find yourself in package hell, trying to wrestle it into doing what you want. That's why I have chosen a higher-level language, the converter can take care of LaTeX. Ideally what I would like would be some sort of template system where you have your TeX (no LaTeX) template with placeholders and your source in reST. Then you run the converter and it puts the two together. I am using
Pelican to do something similar for HTML pages.
I wanted to use a Common Lisp library for generating docbook-xml (because xml itself is horribly verbose), but there was a bug in docbook-xml where ampersands weren't escaped correctly in the transformation from docbook-xml to TeX, at least not when they were the only thing in a title, which is really annoying when you're trying to write a section explaining the '&' operator.
I'll have a look at reStructuredText. Looks good so far, although I really liked the explicit document structure docbook-xml allows for. Having a subsection inside a supersection just seems more reasonable than having it under the supersection.
Zini wrote:@Antsan I don't agree with your position about what is serial and what isn't.
Tutorials are by nature non-serial. Okay, you can have a long tutorial that is split into a series of tutorials. But generally tutorials can cover a wide range of topics that the user should be able to read in any order he wishes (or even skip some).
I think we assign different meanings to the word "tutorial". A tutorial (singular) is intended to be didactic. That means that the author needs to have a didactic intend first, which must rely on some assumption on how much the reader already knows before reading the tutorial. He then builds upon that previous knowledge in an organized manner, thus a tutorial needs to be ordered, at least partially (with branching paths, for example).
If the individual parts are independent enough of each other to be put into an arbitrary order, it's not one tutorial but a collection of tutorials. You yourself seem to use the word in that manner:
I would consider this tour as just a series of introductory tutorials.
And to quote Wikipedia on the matter:
Tutorials usually have the following characteristics:
A presentation of the view usually explaining and showing the user the user interface
A demonstration of a process, using examples to show how a workflow or process is completed; often broken up into discrete modules or sections.
Some method of review that reinforces or tests understanding of the content in the related module or section.
A transition to additional modules or sections that builds on the instructions already provided. Tutorials can be linear or branching.
So tutorials are very obviously not non-serial by nature.
Writing
the OpenMW-CS tutorial would be overkill, as it is hardly a tool that is intended to be used by one person without any collaboration at all – I mean, scripting and landscaping are very different tasks and there are many more in there. Thus you don't write one tutorial that contains both of these tasks but one tutorials for each.
Putting multiple tutorials into a wiki is fine, as I already wrote, but the wiki format is hardly conductive to a tutorial. Thus my confusion.
A wiki for the manual would be okay, but I don't see a problem with the serial format. As I see it the main purpose of the manual is to inform the user about the capabilities of the editor and provide general orientation. I at least would read it from front to back and then use tutorials to figure out how to do specific tasks. Of course the manual would also be used to look up things from time to time. But a table of content will do that job.
OpenMW is a pretty complex program, isn't it? How many people will have the time to read a manual for it front-to-back and why should they bother if they're only going to use half its functionality either way?
Reading a manual to learn something seems kind of strange. How would you even do this? Either you optimize it for teaching (by putting definitions of technical terms upfront and put topics in an order in which they are building on each other) or you optimize it for searching and putting related topics close to each other. The two ways of doing this conflict – you cannot have both. Teaching groups before addition is a bad idea, but in a manual for algebra I'd definitely put groups first.