[Lazarus] Documentation style

[Mattias Gaertner]

On Sat, 23 Jul 2011 14:59:20 +0100
Howard Page-Clark <hdpc at talktalk.net> wrote:

> On 23/7/11 1:20, Hans-Peter Diettrich wrote:
> > During the development of the doc tracker I stumbled over several issues:
> >
> > The English wording often violates my feeling for the language. Can some
> > native English speakers proofread the documentation, and correct
> > stylistic flaws?
> 
> <snip>
> > I also can assign doc files to those people, which are willing to
> > proofread the documentation, so that we can avoid duplicate work.
> 
> I'm a native English speaker, and I'm willing to proofread 
> documentation, and make suggestions for improvements. However, I suspect 
> it is almost an endless task, and probably too much for one person to 
> undertake (although the ideal would be for one English-speaker to 
> undertake this, to get a consistent 'house style' and consistent 
> spelling [UK > US English?]).
> 
> Several questions arise immediately. Where precisely are the original 
> documents? 

The LCL fpdoc files are
lazarus/docs/xml/*.xml

Some package have fpdoc files too.

> How can I (or anyone else) be trusted to edit them correctly?

It's open source. Developers read the patch before committing, users do
bug reports.


> What about formatting style, indenting etc. for code examples? It would 
> be good to have consistency here too. I notice quite a lot of 
> fpc/Lazarus source is quite terse:
> 
> [ result:=i*trunc(x/y); rather than    result := i * Trunc( x/y ); ]

If someone finds it terse or broad depends on the viewer application and
what you are used to.
Some examples need special code formatting to highlight the
important parts of the examples.

Lazarus follows many of the Delphi coding styles:
http://edn.embarcadero.com/article/10280

Maybe someday the viewer can use the jedi code formatter to present
examples in the preferred style of the user.

Mattias