[sldev] Making the build instructions better

[Celierra Darling]

On Wed, Dec 31, 2008 at 2:26 PM, Rob Lanphier <robla at lindenlab.com> wrote:
>
> Currently, the page is split up into platform specific prep pages, and
> then a general "CMake" page after that.  Michelle2's page is
> consolidated into one big page.  Which is the better approach?
>
> Rob

Per-platform would be best for readers, I think, but maintaining
duplicate information is annoying for those editing.  It might be
possible to get the benefits of both - present an overall view to
those maintaining the pages, and specificity to users.  But I'm not
sure if the code would end up too cluttered to be useful in practice.
Here's what I was thinking, though:

One can transclude mainspace articles as if they were templates using
the syntax {{:Article name}}, for example {{:CMake}}.  A hypothetical
page [[Building with Eclipse]] can transclude
{{:CMake|platform=eclipse}}, and there can be code embedded within
[[CMake]] that would filter out all the extraneous information.
However, an editor working on CMake-related documentation can view or
edit [[CMake]], and see all the content for every platform there,
without duplication.

Here's an example of one way this can be done:

Suppose there is a hypothetical {{Specific Instruction}} template
(details at [1]).  Then [[CMake]] might have something like the
following wikitext:

"Blah blah blah blah foo.
{{Specific Instruction|{{{platform|<noinclude>*</noinclude>}}}|eclipse|Nobody's
tried creating an Eclipse project with CMake yet.}}
{{Specific Instruction|{{{standalone|<noinclude>*</noinclude>}}}|Be
sure to set the standalone flag.}}
{{Specific Instruction|{{{os|<noinclude>*</noinclude>}}}|win|Be sure
to get CMake 2.6.99 for Windows due to a bug in prior versions.}}
Bar baz Zardoz."

This would cause the following text to appear on the hypothetical
[[CMake]] page:

"Blah blah blah blah foo. Nobody's tried creating an Eclipse project
with CMake yet. Be sure to set the standalone flag. Be sure to get
CMake 2.6.99 for Windows due to a bug in prior versions. Bar baz
Zardoz."

...and this text on a hypothetical page [[Building with Eclipse]],
calling {{:CMake|platform=eclipse}}:

"Blah blah blah blah foo. Nobody's tried creating an Eclipse project
with CMake yet.  Bar baz Zardoz."

...and this to appear on a hypothetical page [[Building standalone]],
calling {{:CMake|standalone=yes}}:

"Blah blah blah blah foo. Be sure to set the standalone flag.  Bar baz Zardoz."

These conglomerate pages would be desired just for steps which are
similar across platforms, and 'leaf' pages like [[Building with Visual
Studio 2005]] would transclude these pages as necessary, like this:

==Downloading Source Code==
{{:Picking a Branch}}
===SVN Repository===
{{:Download Source|source=svn|os=win}}
===Source Downloads page===
{{:Download Source|source=zip|os=win}}

==Libraries==
{{:Library Downloads|majver=1|minver=20}}

==CMake==
{{:CMake|os=win|platform=vs2005|...}}

Does this seem like something worth pursuing?

Celierra

[1] http://wiki.secondlife.com/wiki/User:Celierra_Darling/Sandbox#Specific_Instruction_Template