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

Otto Dassau otto.dassau at gmx.de
Mon Jul 28 11:03:41 EDT 2008 

On Mon, 28 Jul 2008 08:02:19 -0700
Tara Athan <tara_athan at alt2is.com> wrote:

> 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.

ok, I see

> 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?

yes :)

regards,
 Otto
 
> 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
> >
> >
> >
> >   
> 
>

More information about the Qgis-community-team mailing list