[Qgis-community-team] latex and svn conventions for manual

[Alister Hood]

Hi everyone,
I've only done a few minor edits on the manual, but I have a couple of
thoughts:

> -----Original Message-----
> From: qgis-community-team-bounces at lists.osgeo.org
[mailto:qgis-community-team-
> bounces at lists.osgeo.org] On Behalf Of Tyler Mitchell
> Sent: Thursday, 21 April 2011 12:59 p.m.
> To: Elvis Wang
> Cc: qgis-community-team at lists.osgeo.org
> Subject: Re: [Qgis-community-team] latex and svn conventions for
manual
> 
> I'm late to the discussion, so take it with a grain of salt, but...
> 
> >>> 1 - Is there a minimum amount of changes that should be done
before a
> 'commit'?
> 
> I stick with the rule that I commit every time I realise that I would
not want
> to lose all my changes so far :)
> 
> >>> 2 - Is there a reason for the hard wrapping of the latex code?
> 
> In my opinion, this is helpful for tracking changes over time, since
most
> revision control tools track at a line level.  Meaning, if I have a
line with a
> 1000 characters in it, but only change a few words, it will be harder
for other
> reviewers to understand.  That's from my experience anyway.  Though I
hate
> breaking lines unnecessarily :)

Manually wrapping at a particular width is pretty annoying to do,
especially if you later end up rearranging a sentence or inserting
several words, and need to move the breaks.

Perhaps it would be best to put each sentence on a new line?  I think
this should be OK for change tracking, and not be too annoying to work
with.
 
> >>> 3 - Would it be possible to have a less flat hierarchy of files?
For
> example all the  .tex files are currently in the one folder
'user_guide.tex'
> >>> Would it make sense to structure it so that each folder has a
section?
> 
> It's not a bad idea for more hierarchy, but it does complicate things
a bit
> since then you have to track all those folders and refer to them
directly in
> your master documents.  If it's flat, then you never have to worry
about
> relative paths for images, tex files, etc.

Maybe I'm just not familiar enough with the system, but if I want to
make a change to the manual I sometimes take a while to identify the
right .tex file.  I guess I should just do a search to identify it :)...
but it seems to me that a less flat hierarchy would not be very
user-friendly because it would make it even harder to locate the right
file.  Isn't simpler generally better?


Regards,
Alister