[Qgis-community-team] Re: user guide updates- comments and questions

Tara Athan tara_athan at alt2is.com
Mon Jul 28 11:02:19 EDT 2008 

Hi Otto- sorry, I didn't read your original email carefully.

Originally, I had the macros in the conventions.tex file because they 
were "experimental" and it seemed better and easier to keep them 
together with the conventions content because many changes were being 
made. Also, I was using the content of conventions.tex as the 
documentation for the macros at that time.

Now that the macros are becoming more stable, and they have their own 
documentation and something of a system for categorizing, it does make 
sense to move them into the sty file.

However, I am not sure it make sense for the usage examples that deal 
with the English rather than the latex to be in the sty file - perhaps 
they should be in conventions.tex instead. My original intention was 
that conventions.tex would serve as a template for all other sections. 
So a new documentation writer would start with conventions.tex as a 
guide, and perhaps not realize that additional information was contained 
in the sty file. So I would like to make conventions.tex self-contained, 
where it is not necessary to look at the sty file unless one wants to 
actually change a macro definition.  Does this make sense?

Tara


Otto Dassau wrote:
> Hi Tara,
>
> On Sun, 27 Jul 2008 12:29:08 -0700
> Tara Athan <tara_athan at alt2is.com> wrote:
>
>   
>> Ok, I have removed the macros from the sty file and added a lot of 
>> comments to conventions.tex., including a usage example for each macro.
>>     
>
> ok, this is a possible way, but why do you think it is better to put all the
> macros in the conventions.tex and not in the qgis_style.sty? Isn't it better to
> have all macros in one style file? Because usually people looking for existing
> macros etc. would open the .sty file first and not in conventions.tex.
>
>   
>> 1. I have a few questions for the user quide team. I have noticed that 
>> there is a lot of individual variation about the wording that is used to 
>> describe user instructions. What do you all think about trying to 
>> standardize this wording - is it worth the effort? I don't want to get 
>> too bogged down in unnecessary style requirements when there will be a 
>> great deal of effort needed to update content.
>> Example: different ways to talk about a tool button
>> a. Click on \toolbtntwo{iconname}{Label}
>> b Click on the \toolbtntwo{iconname}{Label} button
>> c. Click on the \toolbtntwo{iconname}{Label} tool
>> d. Click on \toolbtntwo{iconname}{Label} from the toolbar
>> e. Click on \toolbtntwo{iconname}{Label} from the ToolbarName toolbar
>> f. Choose \toolbtntwo{iconname}{Label}
>>
>> and so on- the variations could be endless.
>>
>> If we agree to a consistent style, I can put examples in the usage 
>> section for each macro. My own preference is (e).
>>     
>
> good idea. Please add examples in the usage section for each macro. Since we are
> all no native english speakers, it would be helpful, if you provide a consistent
> style for us. Can you add this to the ManualReleaseChecklist1.0 where you think
> it makes sense?
>
>   
>> 2. Is there a need for a SQL macro? I have noticed that a common 
>> convention for SQL code and keywords is bold uppercase. However, the GUI 
>> does not use this. For example there is a label  "SQL where clause" in 
>> some dialog.
>>     
>
> no - wedon't need a SQL macro, I think
>
>   
>> 3. Would it be possible to include a section covering all the GRASS 
>> modules. Personally, what I would like to have is a listing of each 
>> module with a short description of its purpose and a link to the more 
>> detailed instructions, similar to what is available from the GRASS 
>> toolbox in QGIS. In this way, users who are skimming the user guide to 
>> see if QGIS will do what they want will have information about the 
>> capabilities available through the GRASS modules. At present, you can 
>> only get this by actually opening the GRASS toolbox in QGIS and looking 
>> at each module. And you can only do this after you load a mapset.
>>     
>
> I agree and also already thought about it. Since this is my chapter, I will
> have a look at it and find a solution for that. I added the task to the wiki.
>
>  regards,
>   Otto
>
>   
>> Tara
>>
>>
>> Otto Dassau wrote:
>>     
>>> Hi Tara,
>>>
>>> On Sat, 26 Jul 2008 22:21:11 -0700
>>> Tara Athan <tara_athan at alt2is.com> wrote:
>>>
>>>   
>>>       
>>>> I have started reviewing the macros that have been used in the latex 
>>>> files. I noticed some confusion, including my own confusion, so I would 
>>>> like to clarify a little.
>>>>
>>>> There were a few macros that were written already by Gary, and served a 
>>>> fairly special purpose.
>>>>     
>>>>         
>>> I saw that Gary's macros are currently in qgis_style.sty and the new ones in
>>> conventions.tex. I would propose to cleanup and move all macro definitions
>>>       
> to an
>   
>>> area within qgis_style.sty. This would make it clearer especially when
>>>       
> people
>   
>>> later start to translate.
>>>
>>>   
>>>       
>>>> One of these is \sqltable. I'm not sure of the purpose for this and we 
>>>> should avoid using this until there is more clarity.
>>>>
>>>> There are several styles that can be used for SQL phrases, as well as 
>>>> other similar situations where no other macro seems to really fit.
>>>> 1. When the text is something a user should type in, use \usertext
>>>> 2. When the text is something that the user will see in the GUI, but not 
>>>> click on, use \guilabel
>>>> 3. When the text is something that the user will select from a selection 
>>>> field, use \selectstring. This requires two parameters, one for the 
>>>> label, the other for the selected text.
>>>>
>>>> A similar situation comes up with \fieldname. I believe this was part of 
>>>> the set intend to be used to describe Python coding.
>>>> The set included \classname, \method and \fieldname.
>>>> So "field" in this case refers to data members of a class or object, not 
>>>> a "field" from a table.
>>>> I was confused about this also, and put in a misleading example in the 
>>>> conventions section.
>>>> I have commented out this macro, because it wasn't actually used in the 
>>>> creating_applications section.
>>>> Where it was used, mostly in working_with_vectors, I replaced it with my 
>>>> best guess for the appropriate macro from the list above.
>>>>
>>>> I have added a new macro (\guiheading) for a special circumstance that I 
>>>> noticed in one of the dialogs (Layer Properties for a vector). In this 
>>>> dialog, some labels appear that have a blue background with white text - 
>>>> they are used to provide a heading for sections of metadata. I have not 
>>>> yet added the colors to make this appear right, but the macro is there 
>>>> for your use.
>>>>     
>>>>         
>>> Could we put these detailed macro descriptions commented into the file
>>>       
> with/to
>   
>>> the macro itself, so we can look it up there? There have been already
>>>       
> several
>   
>>> emails with longer descriptions. They are all great and make it a lot
>>>       
> clearer to
>   
>>> review and update the chapters but they are split in several emails. Also
>>>       
> for
>   
>>> new volunteers it would be important to have all these important information
>>> together with the macros itself. Can you add it, please?
>>>
>>>   
>>>       
>>>> So I think working_with_vectors is done for now (Thanks, Stephan!). I 
>>>> will continue to review the sections that you all have modified as my 
>>>> time permits.  Thanks for all your hard work.
>>>>     
>>>>         
>>> thanks for your great ideas!!
>>>  
>>>   Otto
>>>
>>>   
>>>       
>>>> Tara
>>>>
>>>>
>>>>     
>>>>         
>>> No virus found in this incoming message.
>>> Checked by AVG - http://www.avg.com 
>>> Version: 8.0.138 / Virus Database: 270.5.6/1575 - Release Date: 7/26/2008
>>>       
> 4:18 PM
>   
>>>
>>> No virus found in this incoming message.
>>> Checked by AVG - http://www.avg.com 
>>> Version: 8.0.138 / Virus Database: 270.5.6/1575 - Release Date: 7/26/2008
>>>       
> 4:18 PM
>   
>>>
>>>   
>>>       
>>     
>
> No virus found in this incoming message.
> Checked by AVG - http://www.avg.com 
> Version: 8.0.138 / Virus Database: 270.5.6/1576 - Release Date: 7/27/2008 4:16 PM
>
>
>
> No virus found in this incoming message.
> Checked by AVG - http://www.avg.com 
> Version: 8.0.138 / Virus Database: 270.5.6/1576 - Release Date: 7/27/2008 4:16 PM
>
>
>
>   


-- 
My e-mail delivery has been unreliable lately, so I am asking for
return receipts from all my email messages.
OK'ing the return receipt lets me know that my message was delivered.
Thank you.

Tara Athan
Principal, Alternatives to Invasive Species
tara_athan [AT] alt2is.com
707-485-1198
PO Box 415
Redwood Valley, CA 95470

More information about the Qgis-community-team mailing list