2012/6/16 Jody Garnett <jody.garn...@gmail.com>: > Thanks for the review Frank. > > I will try for the following. > > 1) update script to make filenames without blanks
1+ > 2) hunt down missing images (800 seams like a lot; a failure of script etc…) Oh, I guess a lot of these warnings are coming from broken references (e.g. :doc:`A doc page`). I absolutely agree, its should be a goal to fix this and I'll go through if you give a go after conversion from confluence. I assume you used the downloaded "extract" from confluence pages and extracted the content from xml. If this works we could use this to convert the other languages pages of the user docs as well - here we need native speaker support to review the content. > 3) from twitter; replace reference to thumbnails with references to original > images (scaled down to smaller size I found out, that the image references making trouble for rst2pdf builds. If the images are referenced at the right positions with the following scheme the images are rendered correctly in pdf's. In addition to the position we should use figure:: instead of image:: because of additional caption down below the image. It would be much easier to define a style for image captions in css that having "**Figure X : Caption Text**" down below images. .. figure:: images/my/path/to/image.png :width: 20px :other-options: 23424 Figure 1 : Image Caption right here > 4) use /images/... references (so we can move pages into folders after the > conversion) > 5) for the things we expect to be printed (walkthrough 1 etc….) we will put > them on one page Good suggestion! It would be much easier to include/exclude paragraphs. Let's define several pages. > > I would really like to get this to the state where we can use -W again. 1+ Just a hint: I have seen some references that uses fixed pages like "`Running uDig <Running%20uDig.html>`_" in GettingStarted.rst These links should look like this: <Running_uDig> or with an alternative text :doc:`My alternative text <Running_uDig>` To reduce the amount of "not in toctree" warnings we should use ::toctrees:: in Contents page, "Related reference" and "Related concepts" sections. I thought about converting the "concept" pages into glossary entries (http://sphinx.pocoo.org/markup/para.html#glossary) but we can discuss this later... > Is the user doc conversion completed that we can start working on the > content? > > I would like a review of the user doc conversion; we may wish to tweak > things a bit before calling it done and working on the content. > > I guess you are talking about the conversion from confluence. I would > prefer to have file names without blanks, I had a look into the docs > and I'm wondering about missing images (e.g. > user/en/html/Intersect%20Operation.html |image0|, |image1| and > |image3|). Some links are broken (user/en/html/Walkthrough%201.html) > and as a result you get around 800 Warnings from the sphinx build. > Therefor I remove the "turn warnings into error" option "-W". > > IMHO we have some pages with identical content, we should got through > the pages and identify these to clean up. For example : we could move > the "Walkthrough 1" and "Walkthrough 2" pages into getting_started and > remove the getting_started/index page instead. In addition the > converted user documents are not listed in any toctree ... > > > Today I worked on styling (removed background image) and fixed links in the > top navigation div. > > I had a look at the origin odt file and the converted rst's a here some > comments: > - the images are references with pattern |image_name_extension|. I'm not > sure about the current committed rst files but I expected a result like this > from the the BulkConvert class : > .. image::image/import_wiz.png > > I was going to ask you about that; should I generate the following instead: > > .. image:: /image/import_wiz.png > > (This would allow us to group the "tasks pages" into a task folder, since > the "/image/import_wizard.png" would refer to the root directory conf.py is > defined) > > The other more exciting option is to have it generate something like: > > .. image:: > /../../../plugins/net.refractions.udig.catalog.ui/wizban/import_wiz.png > > > This solution has seductive charm but I'm not sure about how much > content we can recycle from the plugins folder. Hmm, some Icons for > sure but a lot of pictures in user/dev docs are screenshots from a > running application with menus and content. For now, let the images > where they are, in case of translations in the future we can move to > an other structure (like osgeo live) where all the images are in the > root folder. > I haven't checked it out, but please correct my if I'm wrong: the > images from walkthrough 1 are walkthrough 1 specific - same with > walkthrough 2. Therefor the images are at the right place I think. > > (This would pull the same image into the docs as is currently sued for the > application) > > Let me know if you think either of these ideas is worth experimenting and > running the conversion again. > > - I tested a bit with sidebars and have a solution for the notes within the > odt files (I assume these were not converted by the odt2sphinx tool and we > have to check ist after conversion): > > You assumption is correct; this was something I did manually after > conversion. > > - I added an additional line in layout.html of the udig theme : {%- block > sidebar2 %}{% endblock %} > - I tested the ..sidebar:: directive in > the ImportDirectlytoTheCatalog.rst file > - we can think about using ..notes:: directives instead but this would > create longer pages than with the sidebar. > > I am not really worried about page length on a web page - so if "notes" is > better just let me know. > > > Last night I pushed sidebars to master but I have no strong opinion > about notes vs. sidebars. The advantage of notes/warnings is that they > can have different styles. Sidebars makes some when creating pdfs with > rst2pdf. > Let's use notes and warnings for the moment. > > Question: For the GeoServer Install workbook I combined everything into a > single page - should I do this for walkthrough 1? > > > Hmm, even no strong opinion about this. It might be a good idea to > have separated (html) pages because of printing a single chapter, > otherwise a browser have no chance to give you a "page from to" range. > Separate is fine. > > _______________________________________________ User-friendly Desktop Internet GIS (uDig) http://udig.refractions.net http://lists.refractions.net/mailman/listinfo/udig-devel
