[Geoserver-devel] new community module on 1.7.x?

[Justin_Deoliveira]

Hi Christian,

I notice you added a new community module named "feature-pregeneralized" on 1.7.x. It is convention to first send mail when you intend to add a new community module, especially on the stable development branch.

It is not a big deal, in every case you will be allowed to do so, but it is mostly for communication purposes. I found myself going over the commit logs this morning and wondering: What is this module? What does it do? etc.. This convention also protects us from random people adding random modules at will.

If it is the case that you can't wait and need to commit some code into the repo, I suggest using the spike section of the repository, as it is open game to anyone with commit access.

Thanks,

-Justin

--
Justin Deoliveira
OpenGeo - http://opengeo.org
Enterprise support for open source geospatial.

[Christian_Mueller]

Yep, sorry, but this module covers only 3 plugin classes I need for geotools community module gt-feature-pregeneralized.

I am in the stage of integrating into geoserver and writing the documentation.

I checked in because i did the same with the GeoXACML module on geoserver trunk and this was ok. The same holds true
for the gt-feature-pregeneralizd module in geotools.

I wanted to write the documentation first and announce afterwards, providing links to an already existing section in the geotools user guid and to a geoserver tutorial.

christian

Justin Deoliveira writes:

Hi Christian,

I notice you added a new community module named "feature-pregeneralized" on 1.7.x. It is convention to first send mail when you intend to add a new community module, especially on the stable development branch.

It is not a big deal, in every case you will be allowed to do so, but it is mostly for communication purposes. I found myself going over the commit logs this morning and wondering: What is this module? What does it do? etc.. This convention also protects us from random people adding random modules at will.

If it is the case that you can't wait and need to commit some code into the repo, I suggest using the spike section of the repository, as it is open game to anyone with commit access.

Thanks,

-Justin

--
Justin Deoliveira
OpenGeo - http://opengeo.org
Enterprise support for open source geospatial.

[Andrea_Aime3]

Christian Müller ha scritto:

Yep, sorry, but this module covers only 3 plugin classes I need for geotools community module gt-feature-pregeneralized.

I am in the stage of integrating into geoserver and writing the documentation.

I checked in because i did the same with the GeoXACML module on geoserver trunk and this was ok. The same holds true
for the gt-feature-pregeneralizd module in geotools.

I wanted to write the documentation first and announce afterwards, providing links to an already existing section in the geotools user guid and to a geoserver tutorial.

The way we do things around here is more of the opposite: announce and
very short description first, and be ready to answer questions, handle
feedback (no module is an island in GeoServer).

Then write docs for everybody else to use.
Mind the first announce mail audience is not "everybody interested
in the GeoServer development" at a large, but just the existing
committers, so it can be very tight and to the point.

Going from there to wider audience requires more communication effort,
but that is not required to just commit and start working on a module.

If you look at the community modules documentation it's said you
need the get go from a PSC member to add a new community module:
http://geoserver.org/display/GEOS/GSIP+22+-+Community+Modules

I also find it an act of courtesy, from a PSC member willing to
add a community module, to ask the get go to at least another
PSC community member, or at the very least send a mail before
doing it. It just keeps the committer group together and show
you're willing to work along other people as opposed to
working alone.

Cheers
Andrea

--
Andrea Aime
OpenGeo - http://opengeo.org
Expert service straight from the developers.

[Christian_Mueller]

Got, it. Next time i will use the spike section. But the commit into the geotools unsupported sections was ok ?. I think we had a lot of mail traffic about this topic.

I did not include these 2 projects in the parent pom, so no build will be affected.

I am about to finish coding, is it ok to put the documentation into the geotools user guide, section 10 and to write a geoserver tutorial ?

thanks

Andrea Aime writes:

Christian Müller ha scritto:

Yep, sorry, but this module covers only 3 plugin classes I need for geotools community module gt-feature-pregeneralized.

I am in the stage of integrating into geoserver and writing the documentation.

I checked in because i did the same with the GeoXACML module on geoserver trunk and this was ok. The same holds true
for the gt-feature-pregeneralizd module in geotools.

I wanted to write the documentation first and announce afterwards, providing links to an already existing section in the geotools user guid and to a geoserver tutorial.

The way we do things around here is more of the opposite: announce and
very short description first, and be ready to answer questions, handle
feedback (no module is an island in GeoServer).

Then write docs for everybody else to use.
Mind the first announce mail audience is not "everybody interested
in the GeoServer development" at a large, but just the existing
committers, so it can be very tight and to the point.

Going from there to wider audience requires more communication effort,
but that is not required to just commit and start working on a module.

If you look at the community modules documentation it's said you
need the get go from a PSC member to add a new community module:
http://geoserver.org/display/GEOS/GSIP+22+-+Community+Modules

I also find it an act of courtesy, from a PSC member willing to
add a community module, to ask the get go to at least another
PSC community member, or at the very least send a mail before
doing it. It just keeps the committer group together and show
you're willing to work along other people as opposed to
working alone.

Cheers
Andrea

--
Andrea Aime
OpenGeo - http://opengeo.org
Expert service straight from the developers.

[Andrea_Aime3]

Christian Müller ha scritto:

Got, it. Next time i will use the spike section. But the commit into the geotools unsupported sections was ok ?. I think we had a lot of mail traffic about this topic.

Yep, but the way to perform the integration was not clear, and not
having read your code, I still don't know how you're pulling it off.

I did not include these 2 projects in the parent pom, so no build will be affected.

The point is not about breaking the build of not, it's about working
as a group as opposed to working stand alone. It's about communication,
not about the technical standpoint.

I am about to finish coding, is it ok to put the documentation into the geotools user guide, section 10 and to write a geoserver tutorial ?

Wiki or sphinx? For sure ok with the wiki, for sphinx I would say
it's ok too, but I'd like to hear Mike/Justin opinion on this one,
not sure we have decided anything about community modules documentation
vs the new documentation system based on Sphinx

Cheers
Andrea

--
Andrea Aime
OpenGeo - http://opengeo.org
Expert service straight from the developers.

[Christian_Mueller]

I am not sure, for geotools, the only possibility is to document in the wiki ?

For geoserver, sphinx will be the future. What happens to the content of the wiki. Will there be a migration ?.

Andrea, say what you prefer at the moment, I will put the geoserver tutorial where you think it fits best.

Andrea Aime writes:

Christian Müller ha scritto:

Got, it. Next time i will use the spike section. But the commit into the geotools unsupported sections was ok ?. I think we had a lot of mail traffic about this topic.

Yep, but the way to perform the integration was not clear, and not
having read your code, I still don't know how you're pulling it off.

I did not include these 2 projects in the parent pom, so no build will be affected.

The point is not about breaking the build of not, it's about working
as a group as opposed to working stand alone. It's about communication,
not about the technical standpoint.

I am about to finish coding, is it ok to put the documentation into the geotools user guide, section 10 and to write a geoserver tutorial ?

Wiki or sphinx? For sure ok with the wiki, for sphinx I would say
it's ok too, but I'd like to hear Mike/Justin opinion on this one,
not sure we have decided anything about community modules documentation
vs the new documentation system based on Sphinx

Cheers
Andrea

--
Andrea Aime
OpenGeo - http://opengeo.org
Expert service straight from the developers.

[Michael_Melvin]

Hi. Could you point me to where this info would go in the wiki? It sounds like something that should go in the Sphinx Developer Manual, and therefore an entry could be added there (somewhere; I don't really play with community modules at all).

The migration has already started from the wiki to Sphinx. You can check out the current status of the User and Developer Manuals here:

http://docs.geoserver.org/1.7.x/

The revolution will not be automatic, though. Given the clutter that is the wiki, if we want something ported, we need to do it manually. Feel free to use JIRA to assign areas of migration that we (probably have) forgotten.

Thanks,
Mike Pumphrey
OpenGeo - http://opengeo.org

Christian Müller wrote:

I am not sure, for geotools, the only possibility is to document in the wiki ?
For geoserver, sphinx will be the future. What happens to the content of the wiki. Will there be a migration ?.
Andrea, say what you prefer at the moment, I will put the geoserver tutorial where you think it fits best.

Andrea Aime writes:

Christian Müller ha scritto:

Got, it. Next time i will use the spike section. But the commit into the geotools unsupported sections was ok ?. I think we had a lot of mail traffic about this topic.

Yep, but the way to perform the integration was not clear, and not
having read your code, I still don't know how you're pulling it off.

I did not include these 2 projects in the parent pom, so no build will be affected.

The point is not about breaking the build of not, it's about working
as a group as opposed to working stand alone. It's about communication,
not about the technical standpoint.

I am about to finish coding, is it ok to put the documentation into the geotools user guide, section 10 and to write a geoserver tutorial ?

Wiki or sphinx? For sure ok with the wiki, for sphinx I would say
it's ok too, but I'd like to hear Mike/Justin opinion on this one,
not sure we have decided anything about community modules documentation
vs the new documentation system based on Sphinx
Cheers
Andrea
--
Andrea Aime
OpenGeo - http://opengeo.org
Expert service straight from the developers.

[Christian_Mueller]

Ah, that is new to me. I think I have to port this stuff first
http://geoserver.org/display/GEOSDOC/Using+the+ImageMosaic+JDBC+Plugin

The module is a geoserver extension.

The new feature-pregeneralized module should also become an extension ( I hope so).

First I have to become familiar with sphinx and port the imagemosiac-jdbc stuff. As a second step I will do feature-pregeneralized documentation.

I will contact you when step one is finished

Mike Pumphrey writes:

Hi. Could you point me to where this info would go in the wiki? It sounds like something that should go in the Sphinx Developer Manual, and therefore an entry could be added there (somewhere; I don't really play with community modules at all).

The migration has already started from the wiki to Sphinx. You can check out the current status of the User and Developer Manuals here:

http://docs.geoserver.org/1.7.x/

The revolution will not be automatic, though. Given the clutter that is the wiki, if we want something ported, we need to do it manually. Feel free to use JIRA to assign areas of migration that we (probably have) forgotten.

Thanks,
Mike Pumphrey
OpenGeo - http://opengeo.org

Christian Müller wrote:

I am not sure, for geotools, the only possibility is to document in the wiki ?
For geoserver, sphinx will be the future. What happens to the content of the wiki. Will there be a migration ?.
Andrea, say what you prefer at the moment, I will put the geoserver tutorial where you think it fits best.

Andrea Aime writes:

Christian Müller ha scritto:

Got, it. Next time i will use the spike section. But the commit into the geotools unsupported sections was ok ?. I think we had a lot of mail traffic about this topic.

Yep, but the way to perform the integration was not clear, and not
having read your code, I still don't know how you're pulling it off.

I did not include these 2 projects in the parent pom, so no build will be affected.

The point is not about breaking the build of not, it's about working
as a group as opposed to working stand alone. It's about communication,
not about the technical standpoint.

I am about to finish coding, is it ok to put the documentation into the geotools user guide, section 10 and to write a geoserver tutorial ?

Wiki or sphinx? For sure ok with the wiki, for sphinx I would say
it's ok too, but I'd like to hear Mike/Justin opinion on this one,
not sure we have decided anything about community modules documentation
vs the new documentation system based on Sphinx
Cheers
Andrea
--
Andrea Aime
OpenGeo - http://opengeo.org
Expert service straight from the developers.

[Michael_Melvin]

Hi Christian. Thanks for helping out. For info on Sphinx (also a work in progress), check out the doc guide:

http://docs.geoserver.org/1.7.x/docguide/

When you migrate that page, I would place it in the Tutorials section, which needs lots of love and migration assistance.

http://docs.geoserver.org/1.7.x/user/tutorials/

Thanks,
Mike Pumphrey
OpenGeo - http://opengeo.org

Christian Müller wrote:

Ah, that is new to me. I think I have to port this stuff first
http://geoserver.org/display/GEOSDOC/Using+the+ImageMosaic+JDBC+Plugin
The module is a geoserver extension.
The new feature-pregeneralized module should also become an extension ( I hope so).
First I have to become familiar with sphinx and port the imagemosiac-jdbc stuff. As a second step I will do feature-pregeneralized documentation.
I will contact you when step one is finished

Mike Pumphrey writes:

Hi. Could you point me to where this info would go in the wiki? It sounds like something that should go in the Sphinx Developer Manual, and therefore an entry could be added there (somewhere; I don't really play with community modules at all).
The migration has already started from the wiki to Sphinx. You can check out the current status of the User and Developer Manuals here:
http://docs.geoserver.org/1.7.x/
The revolution will not be automatic, though. Given the clutter that is the wiki, if we want something ported, we need to do it manually. Feel free to use JIRA to assign areas of migration that we (probably have) forgotten.

Thanks,
Mike Pumphrey
OpenGeo - http://opengeo.org

Christian Müller wrote:

I am not sure, for geotools, the only possibility is to document in the wiki ?
For geoserver, sphinx will be the future. What happens to the content of the wiki. Will there be a migration ?.
Andrea, say what you prefer at the moment, I will put the geoserver tutorial where you think it fits best.

Andrea Aime writes:

Christian Müller ha scritto:

Got, it. Next time i will use the spike section. But the commit into the geotools unsupported sections was ok ?. I think we had a lot of mail traffic about this topic.

Yep, but the way to perform the integration was not clear, and not
having read your code, I still don't know how you're pulling it off.

I did not include these 2 projects in the parent pom, so no build will be affected.

The point is not about breaking the build of not, it's about working
as a group as opposed to working stand alone. It's about communication,
not about the technical standpoint.

I am about to finish coding, is it ok to put the documentation into the geotools user guide, section 10 and to write a geoserver tutorial ?

Wiki or sphinx? For sure ok with the wiki, for sphinx I would say
it's ok too, but I'd like to hear Mike/Justin opinion on this one,
not sure we have decided anything about community modules documentation
vs the new documentation system based on Sphinx
Cheers
Andrea
--
Andrea Aime
OpenGeo - http://opengeo.org
Expert service straight from the developers.

[Christian_Mueller]

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

[Michael_Melvin]

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.

* 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

[David_Winslow]

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

[Michael_Melvin]

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

[Christian_Mueller]

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

[Michael_Melvin]

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
Geoserver-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel

[Christian_Mueller]

Applied :file:, :command: and :menuselection: directives to both tutorials.

Altered the titles as you proposed and removed the ..note:: where you suggested.

Applied the ..code:: xml where necessary

One question, is there a directive to indicate "Pressing a button on a form", at the moment I used bold.

Mike Pumphrey writes:

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
Geoserver-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel

[David_Winslow]

For GUI elements that aren't hierarchical, there is the :guilabel:
directive.

http://sphinx.pocoo.org/markup/inline.html#other-semantic-markup
contains a list of all these types of roles provided by default in
Sphinx. Keep in mind that we can ignore these or create more as seems
appropriate, but taking advantage of what's already there seems like a
good strategy starting out.

--
David Winslow
OpenGeo - http://opengeo.org/

On Tue, 2009-06-09 at 17:06 +0200, Christian Müller wrote:

Applied :file:, :command: and :menuselection: directives to both tutorials.

Altered the titles as you proposed and removed the ..note:: where you
suggested.

Applied the ..code:: xml where necessary

One question, is there a directive to indicate "Pressing a button on a
form", at the moment I used bold.

Mike Pumphrey writes:

> 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
>>>>> Geoserver-devel@lists.sourceforge.net
>>>>> https://lists.sourceforge.net/lists/listinfo/geoserver-devel
>>>>
>>
>>

------------------------------------------------------------------------------
Crystal Reports - New Free Runtime and 30 Day Trial
Check out the new simplified licensing option that enables unlimited
royalty-free distribution of the report engine for externally facing
server and web deployment.
http://p.sf.net/sfu/businessobjects
_______________________________________________
Geoserver-devel mailing list
Geoserver-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geoserver-devel