dominique.faure at gmail.com
Fri Jan 27 10:10:56 CST 2006
2006/1/27, Bronwyn Boltwood <arndis at gmail.com>:
> On 1/27/06, Patrick R. Michaud <pmichaud at pobox.com> wrote:
> > On Thu, Jan 26, 2006 at 11:43:27PM -0800, Phil Seyer wrote:
> > > In the documentation I have trouble telling when I need to substitue my own specific data into the command line.
> > >
> > Do you have any suggestions how we could better indicate where
> > substitutions should take place...? Christian Ridderström suggests
> > $DefaultPasswords['edit'] = crypt('<edit_password>');
> > my only concern is that people will start to assume that the angle
> > brackets are part of the syntax.
> A lot of the code fragments are used verbatim, so it's understandable
> that non-coders don't know what should be changed and what should not.
> Somebody would inevitably assume the angle brackets belonged there.
> The traditional method, in a book, would be to use a typographic
> convention. Then I realized that most of the instances where we need
> the convention are in uninterpreted blocks, where we can't style the
> text. So the best solution is probably to make it clear in the
> accompanying documentation which chunk should be changed and what to.
Why not defining one for PmWiki documentation?
Here's one inspirated from those provided with animal covered books
(May be a PmWiki.Convention candidate):
(:title Conventions Used in This Documentation:)
The following typographical conventions are used in this documentation:
Indicates new terms where they are defined, URLs, variables in text,
user-defined files and directories, commands, markups, file
extensions, filenames, directory or folder names, and UNC pathnames.
Indicates command-line computer output, code and markup examples, and
:'''@@Constant width bold@@''':\
Indicates user input in examples.
:''@@Constant width italic@@'':\
Indicates variables in examples. It is also used to indicate variables
or user-defined elements within italic text (such as pathnames or
filenames). For instance, in the code ''\Windows\@@username@@'',
replace username with your name.
More information about the pmwiki-users