Re: Docs diffs

Adriaan de Groot wrote:

> Several attached diffs:
> 
> * tech.diff fixes ref-attributes.sgml, which used lots of &nbsp
> entities (note missing semicolon) and had an unbalanced tgroup.

I'll include it.

> * install.diff is a pretty substantial rewrite of user-install.sgml.
> It tries to collapse a table and a programlisting into one, while
> adding explanations. 

I'm glad you made this more verbose.  The old text was not much more
than a summary.

> One sentence in the original mystifies me:
> 	  All these dependencies that &Aap; adds are at the toplevel
> 	  (unlike "clean" and "cleanmore", which are done for each
> 	  parent and child recipe).
> why (or how) is this relevant? Can you notice this at all as an AAP user?

This is relevant when splitting up a big project into sub-projects.
Each sub-project can have it's own clean target.  Thus it doesn't need
to worry about what happens in other recipes.  The other targets for
installing are global, there is only one for the whole project.  This
means that installable files must be appended to the INSTALL_ variables
and care must be taken that the paths are not relative to a subdirectory.

Does that clear it up?

I had some trouble applying this patch.  Apparently you addeed <!--/-->
items!.  And a trailing slash in <colspec  .../>.  I removed a <para>
inside an <entry>, that is not allowed in my sgml.  And the "span"
attribute is not supported.  Unfortunately, tables require naming the
columns for a data cell to span multiple columns.  There is an example
at the start of ref-commands.sgml.  Very clumsy solution, but that's how
it is to be done.  I'll fix that.

"No default settings for libtool libraries have been added to &Aap;
yes."  I suppose that last "yes" should be "yet"?

By the way, I'm having lots of trouble accessing pages on sourceforge
(both for Vim and for Aap).  Do others have this problem or is it just
me?

> I've gone and used <replaceable> here and there - I don't think the tag 
> appears anywhere else in the docs till now. I'd also like to mark up some 
> parts with <note> or <warning>, and this reminds me that only Bram
> knows what the markup conventions are, and it's hard to follow rules
> that aren't written down. As a random start to documenting the markup
> style:
>
> * exec.diff adds a comment showing some of the markup conventions, as near as 
> I understand them.

Yes, we need a README for the docs that explains what tags are used for
which items.  I would prefer adding a separate file instead of putting
this in exex.sgml.  I'll use your comments to start that.  Here is a
first version:

-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
Tagging conventions used in the Aap docbook documentation:

<filename>	Filenames and paths: <filename>main.aap</filename>

<command>	Shell commands: <command>aap install</command>

<userinput>	What the user has to type something at a prompt:
		<userinput>yes</userinput>

<link>		Aap command names: <link linkend="cmd-conf">:conf</link>

<programlisting>
		Example recipes.  Note that the </programlisting> must be in
		the first column to avoid a blank line at the end.

<literallayout>
		Listing of shell commands and their output.


Other conventions:

- Program listings are indented 4 spaces and line-numbered (if needed) with
  just numbers (no dots).

- Aap commands as examples in running text get double quotes: ":do compile
  $source"

- Variable names get $, no markup
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

> * tutor-distribute.diff  shortens the tutorial on uploading a little - but 
> perhaps there was a special reason to use :include and do some weirdness in 
> the original example there? 

Good idea to avoid introducing ":include" here.  Keeps it to the point.

> I'm rather inclined to swap "distributing a program" and "publishing a 
> website", and moving the description of {publish} to the "distributing a 
> program" part. Then "compiling" and "distributing" are fairly generic and 
> abstract, while "publishing" puts them to use for a concrete case (one that's 
> pretty neat as well).

That sounds logical.  Care should be taken that a few references between
the chapters are fixed.  The "distributing a program" also needs to be
changed to explain using "aap -f http://site/main.aap" instead of
downloading the recipe separately.  That was added after writing the
docs.  It is a much nicer example than "aap refresh" (although that one
can stay as a second step, for upgrading to a later version).

> Would it make sense to index the tutorial some? There's lots of little notes 
> and tips and tricks in there that you can never find except by reading the 
> whole thing (stuff about indentation, $TOPDIR, comes to mind).

The tutorial was written to teach the reader several things, one step at
a time.  You should read it from start to end.  It's not a reference
manual where you randomly lookup things.  Although the reader might come
back there after reading it once, e.g., to look for an example.


Thanks for your remarks and patches.  Good documentation is very
important for people who start using Aap.

-- 
$ echo pizza > /dev/oven

 /// Bram Moolenaar -- [email protected] -- http://www.Moolenaar.net   \\\
///          Creator of Vim - Vi IMproved -- http://www.Vim.org          \\\
\\\              Project leader for A-A-P -- http://www.A-A-P.org        ///
 \\\  Help AIDS victims, buy here: http://ICCF-Holland.org/click1.html  ///


-------------------------------------------------------
This SF.net email is sponsored by: VM Ware
With VMware you can run multiple operating systems on a single machine.
WITHOUT REBOOTING! Mix Linux / Windows / Novell virtual machines
at the same time. Free trial click here:http://www.vmware.com/wl/offer/358/0