As much as I love consistency and perfect form, I think that keeping things moving is preferable. So commit away. Docs can always be edited later if need be...
Thanks, Mike Pumphrey OpenGeo - http://opengeo.org Christian Müller wrote: > 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 >>>> [email protected] >>>> 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 [email protected] https://lists.sourceforge.net/lists/listinfo/geoserver-devel
