[sldev] Better build instructions

[Dale Mahalko]

On Mon, Jul 28, 2008 at 10:03 AM, Alissa Sabre <alissa_sabre at yahoo.co.jp> wrote:
> We are using Mediawiki, so all past versions of a page are always
> available through _history_ tab.  Historical build informations are
> never lost.  We "re-edit the same page over and over", keeping older
> versions.

Since history pages cannot be edited as branches of the current page
it is difficult to impossible to update an old version of a page which
just so happens to be incorrect and needs to be fixed because the
build information was wrong way back when, or new information needs to
be added.


>> It takes about 30 seconds to edit the current (old) build page, copy
>> the text, make a new page for the next viewer, paste, and then update
>> this new page to make note of any changes.
>
> Please don't do it, even if it is handy for you, because:
>
> - If you edit an existing page, Mediawiki's built-in compare function
>  shows your changes very easily.  However, if you copy the content
>  and rewrite slightly, it will be very hard for other people to find
>  what change you made over the previous version.  It is especially
>  true for a developer who has build previous versions and wants to
>  know what is the difference for the latest version.
>
> - It makes maintaining other language versions (translations) of the
>  page very hard, partly because it is hard to find changes (see
>  above), and partly because you probably don't copy the corresponding
>  translated pages.

If this software has the full capabilities of Wikipedia, then common
elements that repeat over and over can be handled with templates.

This way you can easily have 20 separate build pages which all refer
to the same particular build tool or library version, and encapsulate
the info for the tools or libraries inside templates. Changing the
template auto-updates all other pages using it. If a new tool or
library release will need different instructions, make a new template
to be used for future versions of the page.

{{Common_Compile_Intro-Viewer_Series_1.22}}

For this particular version you need to blah blah blah.

{{Intro-Compiling_With_VS2005}}

Tools used to compile this viewer:
{{BuildTool-Cygwin_x.x.x}}
{{BuildTool-CMake_x.x.x}}

Libraries used to compile this viewer:
{{BuildLibrary-FMod x.x.x}}

{{Intro-Compiling_With_VS2008}}

Tools used to compile this viewer:
{{BuildTool-Cygwin_x.x.x}}
{{BuildTool-CMake_x.x.x}}

Libraries used to compile this viewer:
{{BuildLibrary-FMod x.x.x}}

By doing this, the majority of the page may just be template links
with just a few sentences describing the specific details of this
release, and each release can have its own custom page which can be
easily updated separately of others.


- Scalar Tardis / Dale Mahalko