Should I wait until you have added all these conventions to the
geoserver/sphynx guide or just use the hints from our mails ?
Mike Pumphrey writes:
> Cool. Do you see any other directives in the list that would be good for
> us to use, so I can commit all at once?
>
> To recap:
>
> When writing a shell command [or just running a program?]:
>
> :command:`nameofcommand`
>
> When writing about a file or path:
>
> :file:`path/file` (for when you set a file/path explicitly)
> :file:`{path}/file` (for when you want to show that the {path} is
> variable)
>
> But the original question is how this sort of content should be styled,
> regardless of how Sphinx handles the syntax. I'm still a big fan of
> monospace for files/paths and bold for commands. I generally reserve
> italics for actual textual emphasis, but I don't use it all that much.
> Does this seem approximately on base?
>
>
>
>
> Thanks,
> Mike Pumphrey
> OpenGeo - http://opengeo.org
>
>
> David Winslow wrote:
>> On Fri, 2009-06-05 at 17:26 -0400, Mike Pumphrey wrote:
>>> Hello Christian. Apologies for the extremely late response. Thanks for
>>> breaking the ice on the tutorials section! We need many more of those.
>>>
>>> I have mainly nitpicky stylistic suggestions.
>>>
>>> * I try to make inline commands, paths, and filenames be ``monospaced``
>>> instead of **bolded** (which I reserve for vocabulary words). Makes
>>> them easier to be visually linked to the code blocks (soon, the theme
>>> for monospace will be the same color too, making the link more
>>> explicit). Note to self that these guidelines aren't in the Docguide,
>>> but will be soon.
>>
>> In fact Sphinx provides a special role for
>> commands: :command:`command` . This should be used for the names of
>> commandline tools (like :command:`rm`, not like :command:`rm
>> -rf /path/to/oversized/directory`).
>>
>> Similarly, for paths and filenames there is a role :file: with support
>> for bracketed placeholders:
>> :file:`{GeoServer data directory}/styles/{Your style name}.sld`
>>
>> I would recommend using these to let sphinx do the heavy lifting with
>> making things look nice. Mike, could you add this while you're updating
>> the docs?
>>
>> --
>> David Winslow
>> OpenGeo - http://opengeo.org/
>>
>>> * I would take the note on "Who [how?] many pyramids are needed?" and
>>> turn that into a standard heading. That way you have access to code
>>> blocks, which given the content would make it easier to read. The
>>> second note "A few words about size" is fine.
>>>
>>> * In the "configuring the new map" section, since your code blocks are
>>> XML, you should use ".. code-block:: xml" (see
>>> http://docs.geoserver.org/1.7.x/user/styling/sld-introduction.html) to
>>> get syntax highlighting.
>>>
>>> * I just found out that there's a nicer way of doing menu traversal
>>> descriptions: " :menuselection:`Start --> Programs` ". I'll need to go
>>> through all my docs and fix that now. :)
>>>
>>> * Finally, I think it would be nice to have more descriptive titles for
>>> these tutorials. Like "Storing a coverage in a JDBC database" and
>>> "Using the GeoTools feature-pregeneralized module" or something.
>>>
>>> Generally, it sounds like you're pretty solid on these tutorials (I
>>> haven't tested for accuracy here, just basic style). If there's any
>>> other questions you have on Sphinx work, I'm happy to guide.
>>>
>>>
>>> Thanks,
>>> Mike Pumphrey
>>> OpenGeo - http://opengeo.org
>>>
>>>
>>> Christian Müller wrote:
>>>> Hi Mike, could you please take a quick look at the migrated tutorial,
>>>> it is in the 1.7.x branch. If everything is ok, I would start writing
>>>> the next tutorial for the feature-pregeneralizd module.
>>>> thanks
>>> ------------------------------------------------------------------------
>>> ------
>>> OpenSolaris 2009.06 is a cutting edge operating system for enterprises
>>> looking to deploy the next generation of Solaris that includes the
>>> latest innovations from Sun and the OpenSource community. Download a
>>> copy and enjoy capabilities such as Networking, Storage and
>>> Virtualization. Go to: http://p.sf.net/sfu/opensolaris-get
>>> _______________________________________________
>>> Geoserver-devel mailing list
>>> Geoserver-devel@lists.sourceforge.net
>>> https://lists.sourceforge.net/lists/listinfo/geoserver-devel
>>
------------------------------------------------------------------------------
OpenSolaris 2009.06 is a cutting edge operating system for enterprises
looking to deploy the next generation of Solaris that includes the latest
innovations from Sun and the OpenSource community. Download a copy and
enjoy capabilities such as Networking, Storage and Virtualization.
Go to: http://p.sf.net/sfu/opensolaris-get
_______________________________________________
Geoserver-devel mailing list
Geoserver-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel
