View Issue Details

IDProjectCategoryView StatusLast Update
0000830ScribusDocumentationpublic2005-01-06 18:23
Reportermhanski Assigned Tocbradney  
PrioritynormalSeverityfeatureReproducibilityN/A
Status closedResolutionfixed 
PlatformAMD Athlon XP 3000+OSMandrake Linux OfficialOS Version10
Product Version1.2 
Fixed in Version1.2.1cvs 
Summary0000830: Integration of 3rd party docs within Scribus
DescriptionIt would be a usable feature, if you offerred the users the integration of 3rd party documentation packages into the Scribus Help menu, just the same way it works with 3rd party plug-ins. The Scribus Team could define, how to create installable Scribus documentation packages, and it were up to the users to get such packages and install them independently of the official manual. These docs should then appear within the Help menu _regardless_ the GUI language, since multilinguality is pretty common nowadays. E.g., a Canadian with Polish-German ancestors could have a Help menu like this:

Help:
 -About Scribus
 -About QT
 -Scribus Manual //The official manual
 -Scripter Manual
 -RĂ©alisation... (fr)
 -Erste Schritte mit Scribus (de)
 -Pierwsze kroki ze Scribusem (pl)
 -etc.
Additional InformationThis idea evolved from these mails:
http://nashi.altmuehlnet.de/pipermail/scribus/2004-June/005520.html
http://nashi.altmuehlnet.de/pipermail/scribus/2004-June/005521.html
TagsNo tags attached.
Patch

Relationships

related to 0001389 closedsubik short words for 1.2.1(cvs) 
related to 0001537 closedcbradney 3rd party documentation: Polish FreedomYug tutorial to include into help browser 
related to 0003622 feedback Allow Scribus to search for additional directories for docs 

Activities

malex

2004-06-24 21:18

administrator   ~0001840

Macej,

I'm with you on this topic. However, the hardest part or a biggest obstacle on using some structured text for writing docs be it Docbook XML or Docutils ReSt that I personally tried to pitch to Peter for this same reason is the transformation step. If you could write a transformation routine that would produce HTML with the exact constraints that Peter and Craig would specify, I think you'd win 80% of their approval. It's my opinion and the shields are down. Fire away.

Alex.

mhanski

2004-06-25 09:25

developer   ~0001844

Alex,
I'm afraid, I'm the wrong (means: not very knowlegeable) person to write such a transformation routine. Besides, i think it's a good idea, but this is not, what this feature request is about. I'm pretty sure, if you submitted it with another feature request and the Scribus team specified, _what_ can be done to gain 100% of their approval, sooner or later there would be someone able to deliver such a transformation routine.

As for this feature request, IMO it would be sufficient, if Scribus team made it possible to include additional, pluggable, unofficial documentation packages into the Help menu, regardless what they look like.

cbradney

2004-06-27 23:01

administrator   ~0001849

Its not about what they look like, as such, but getting them to work. The Help Browser's capabilities are very limited in terms of HTML and CSS and therefore many things often need hand tweaking.

As for adding menu items on the fly.. well.. its possible. Need to think of best way to go ahead with such a thing.

deejay1

2004-07-01 22:09

developer   ~0001866

Maybe the menu could look something like this:
Scribus Manual:
->EN->Official
->EN->Third party
->PL->Official
->PL->Third party
Scripter:
->EN......

With a direcotory structure like:
/%{prefix}/share/scribus/doc/<plugin or part of scribus>/<language>
and Scribus on loading could read a small XML file inside <language> and <plugin...> with a proper description of the docs even with proper i18n in it.
Or would it be too much to load on startup/first use?

cbradney

2004-12-30 12:05

administrator   ~0003295

3rd party sections can now be added under the tutorial section of help. ie.. in the help browser, tutorial menu. When started it will scan under $prefix/share/scribus/doc/en/tutorials/* and add in any dir in there that has a menu.xml file. An example will come of this with the FreedomYug tutorial.

mhanski

2005-01-05 15:52

developer   ~0003349

Excellent, good to know, you've been working on it! I'd love to give it a try, could you post a simple example of such a menu.xml file here?

What would happen, if I placed my tutorial under $prefix/share/scribus/doc/pl/tutorials/*? Would the english docs be replaced by an almost empty Polish help browser, including only this tutorial? Or is there any chance to have non English 3rd party docs and English official docs in Scribus at the same time?

cniehaus

2005-01-05 16:06

reporter   ~0003350

a) can't this be closed?

b) could you simply open a browser for more complex html-files? In wxWidgets you can found out the default browser, so I guess Qt is able to do it.

cbradney

2005-01-05 17:55

administrator   ~0003351

The help browser uses the GUI language only. It does not allow tutorials to be brought in from dirs other than doc/guiLanguage/tutorials. It requires a basic menu.xml in doc/guiLanguage/ to create the Tutorials menu itself. It then scans dirs under the doc/guiLanguage/tutorials to see if the contain a menu.xml file for the tutorial itself.

<?xml version="1.0" encoding="UTF-8"?>
<menu>
    <submenuitem text="Get Started With Scribus" file="tutorials/freedomyug/scribustutorial1.html">
        <submenuitem text="Page 2" file="tutorials/freedomyug/scribustutorial2.html"/>
    </submenuitem>
</menu>

---

a) Yes, this can be closed if Maciej thinks so
b) Dont know if Qt can.

2005-01-05 20:44

 

help_browser1.png (67,288 bytes)   
help_browser1.png (67,288 bytes)   

2005-01-05 20:45

 

help_browser2.png (121,159 bytes)   
help_browser2.png (121,159 bytes)   

mhanski

2005-01-05 21:02

developer   ~0003361

Last edited: 2005-01-05 21:46

<quote1>3rd party sections can now be added under the tutorial section of help. ie.. in the help browser, tutorial menu. When started it will scan under $prefix/share/scribus/doc/en/tutorials/* and add in any dir in there that has a menu.xml file. An example will come of this with the FreedomYug tutorial.</quote1>

<quote2>The help browser uses the GUI language only. It does not allow tutorials to be brought in from dirs other than doc/guiLanguage/tutorials. It requires a basic menu.xml in doc/guiLanguage/ to create the Tutorials menu itself.</quote2>

Curious, if symlinks outside of $prefix/share/scribus/doc/pl would be followed. We could combine third party docs for various languages, without having to copy them every time anew into each doc/guiLanguage/

<quote3>
 It then scans dirs under the doc/guiLanguage/tutorials to see if the contain a menu.xml file for the tutorial itself.</quote3>


Just to start with: neither the behaviour described in <quote1> nor that in <quote3> doesn't seem to work for me by now. I've tested it with many combinations and today's CVS and haven't been able to include the Freedomyug tutorial. Perhaps I'm missing something obvious.

Scenario 1: Polish GUI language, the installed English documentation will be displayed by default (see screen shot help_browser1.png). Prefix is /usr/local/share, documentation in located in $prefix/share/scribus/doc/en, the Freedomyug tutorial is placed in $prefix/share/scribus/doc/en/tutorials/freedomyug. I've tried to put the accostumed menu.xml into every directory (en, en/tutorial, en/tutorial/freedomyug) without any effect.

Scenario2: Switched the GUI language to English and repeated the steps from scenario1. Same results.

Scenario3: Copied contents of $prefix/share/scribus/doc/en into new created $prefix/share/scribus/doc/pl and repeated the steps from scenario1 with Polish GUI language - the same results. BTW, if I put menu.xml into $prefix/share/scribus/doc/pl and replace the old menu.xml, there will be only an empty help browser without any contents (screen shot help_browser2.png).

BTW, a strange detail, which perhaps deserves a separate bug: I created an empty $prefix/share/scribus/doc/pl directory, the help browser showed no contents. I placed there the menu.xml taken from $prefix/share/scribus/doc/en (beware, no other contents!), and the help browser showed all pages! As far as I can see, menu.xml contains only relative links, it looks like the help browser takes the docs pages from $prefix/share/scribus/doc/en, regardless which GUI language is in use.

cbradney

2005-01-05 21:55

administrator   ~0003362

<?xml version="1.0" encoding="UTF-8"?>
<menu>
    <submenuitem text="Get Started With Scribus" file="scribustutorial1.html">
        <submenuitem text="Page 2" file="scribustutorial2.html"/>
    </submenuitem>
</menu>

Is the new format. Ive just updated CVS with some fixes to the helpbrowser. It now works properly handling languages with multiple tutorials installed properly.

2005-01-06 10:26

 

2005-01-06 10:28

 

2005-01-06 10:29

 

mhanski

2005-01-06 10:50

developer   ~0003363

Some more testing:)

Good news: I've finally managed to install 3 sample tutorials (see attached help_browser_PL_with_3_tutorials.png).

Not so good news: it only works, if the tutorials are placed under $prefix/share/scribus/doc/en/tutorials/*.

Scenario 1: Polish GUI language, Freedomyug installed under $prefix/share/scribus/doc/pl/tutorials/* - the help browser ignores the files in prefix/share/scribus/doc/pl/tutorials/freedomyug/* and reads the english files from prefix/share/scribus/doc/en/tutorials/freedomyug/* (see screen shot help_browser5_PL_with_wrong_contents.png)

Scenario 2: $prefix/share/scribus/doc/pl/ contains only menu.xml and no files, but the help browser displays tutorial.html from the en docs (see help_browser4_with_wrong_contents.png). The language of the docs seem to be hardcoded, somewhere...

cbradney

2005-01-06 11:08

administrator   ~0003364

I have 1 under en and 2 under pl and I can get to the en one normally and the pl ones (have edited content to show them) via scribus -l pl. If the help browser fails to find menu.xml files in the main directory it will revert to en. If you have a menu.xml with links to files that dont exist, then yes, it will show the english ones if they exist.

2005-01-06 11:21

 

pl.tar.bz2 (20,853 bytes)

cbradney

2005-01-06 11:30

administrator   ~0003365

Maciej, you will have some text output to console when opening the help browser in both langs... what is it?

mhanski

2005-01-06 11:30

developer   ~0003366

Have done the same as you ("scribus -pl" and "scribus -l en"), but with no satisfactory results. The attached pl.tar.bz2 contains a simplified version of $prefix/share/scribus/doc/pl/* - as you can see, there is a menu.xml and there are correct relative links in it, and I edited scribustutorial1.html, too. Could you install it, launch "scribus -l pl" and see, what you'll get - I've got help_browser5_PL_with_wrong_contents.png

mhanski

2005-01-06 11:52

developer   ~0003367

[maciej@chello212017080060 maciej]$ scribus -l pl
pl
/usr/local/share/scribus/doc/pl/menu.xml
QTextImage: no mimesource for scribusTutorial_html_m40588a0.jpg
QTextImage: no mimesource for 100002010000003000000030BBFF9978.png


q[maciej@chello212017080060 maciej]$ scribus -l en
en
/usr/local/share/scribus/doc/en/menu.xml
QTextImage: no mimesource for scribusTutorial_html_m40588a0.jpg
QTextImage: no mimesource for 100002010000003000000030BBFF9978.png

cbradney

2005-01-06 12:10

administrator   ~0003368

Ok.. mistake on your part: You had no tutorial.html as you had specified in your menu.xml. Any missing file will revert it to looking for English.

Second, you had no index.html. Not having the index.html meant it was immediately reverting to English

Mistakes on my part: You shouldnt need an index.html nor a file for the Tutorials menu item. Check out CVS to get the new file and please retest.

2005-01-06 14:06

 

help_browser_PL_superb.png (21,512 bytes)   
help_browser_PL_superb.png (21,512 bytes)   

mhanski

2005-01-06 14:20

developer   ~0003371

<quote>Ok.. mistake on your part: You had no tutorial.html as you had specified in your menu.xml. Any missing file will revert it to looking for English.</quote>

Ok, tutorial.html did the trick, see help_browser_PL_superb.png :) Many thanks, well done.

BTW, it would be fine, if the area name "Tutorials" in <area text="Tutorials" file="tutorials.html"> could somehow be made translatable too, because it will be always displayed in English (see the last screen shot). Perhaps the title element from tutorial.html could be displayed instead.

Anyhow, that's a tweak, which shouldn't stop you from closing this feature request, if nobody objects. The "b)" proposal of cniehaus, that I consider very interesting, can be submitted with a separate feature request.

Once again, many thanks for being so patient.

cbradney

2005-01-06 15:40

administrator   ~0003374

Ok, give it a try now. Please add a section option to your /doc/pl/menu.xml like so:
<area text="Things to learn from" file="tutorials.html" section="tutorials">

Of course, replace the text attribute with whatever text you want. Let me know how it goes.

Suggestion b) wont be followed in 1.2.x.

2005-01-06 18:03

 

help_browser_PL_most_superb.png (18,895 bytes)   
help_browser_PL_most_superb.png (18,895 bytes)   

mhanski

2005-01-06 18:12

developer   ~0003378

It works just perfect now (see the screen shot help_browser_PL_most_superb.png).

It's definitely ripe for closing. BTW, what wonderful stuff for the next how to "How to include 3rd party and plug-in documentation" we now have :) (thinking of Petr and his Short Words docs, which now land in $prefix/share/scribus/doc/scribus-short-words).

cbradney

2005-01-06 18:21

administrator   ~0003379

Cool :) will close.

BTW, that'd be
$prefix/share/scribus/doc/en/tutorials/scribus-short-words
$prefix/share/scribus/doc/cs/tutorials/scribus-short-words
$prefix/share/scribus/doc/pl/tutorials/scribus-short-words

:)

Issue History

Date Modified Username Field Change
2004-06-24 15:48 mhanski New Issue
2004-06-24 21:18 malex Note Added: 0001840
2004-06-25 09:25 mhanski Note Added: 0001844
2004-06-26 05:21 plinnell Assigned To => plinnell
2004-06-26 05:21 plinnell Reproducibility always => N/A
2004-06-26 05:21 plinnell Status new => assigned
2004-06-26 05:21 plinnell Category General => Documentation
2004-06-26 05:21 plinnell Product Version => 1.2
2004-06-27 23:01 cbradney Note Added: 0001849
2004-07-01 22:09 deejay1 Note Added: 0001866
2004-11-07 19:32 mhanski Relationship added related to 0001281
2004-11-07 19:36 mhanski Relationship deleted related to 0001281
2004-12-08 19:18 cbradney Assigned To plinnell => cbradney
2004-12-30 12:05 cbradney Note Added: 0003295
2005-01-05 15:52 mhanski Note Added: 0003349
2005-01-05 16:06 cniehaus Note Added: 0003350
2005-01-05 17:55 cbradney Note Added: 0003351
2005-01-05 20:44 mhanski File Added: help_browser1.png
2005-01-05 20:45 mhanski File Added: help_browser2.png
2005-01-05 21:02 mhanski Note Added: 0003361
2005-01-05 21:46 mhanski Note Edited: 0003361
2005-01-05 21:55 cbradney Note Added: 0003362
2005-01-06 10:26 mhanski File Added: help_browser4_PL_with_wrong_contents.png
2005-01-06 10:28 mhanski File Added: help_browser5_PL_with_wrong_contents.png
2005-01-06 10:29 mhanski File Added: help_browser_PL_with_3_tutorials.png
2005-01-06 10:50 mhanski Note Added: 0003363
2005-01-06 11:08 cbradney Note Added: 0003364
2005-01-06 11:21 mhanski File Added: pl.tar.bz2
2005-01-06 11:30 cbradney Note Added: 0003365
2005-01-06 11:30 mhanski Note Added: 0003366
2005-01-06 11:52 mhanski Note Added: 0003367
2005-01-06 12:10 cbradney Note Added: 0003368
2005-01-06 14:06 mhanski File Added: help_browser_PL_superb.png
2005-01-06 14:20 mhanski Note Added: 0003371
2005-01-06 15:40 cbradney Note Added: 0003374
2005-01-06 18:03 mhanski File Added: help_browser_PL_most_superb.png
2005-01-06 18:12 mhanski Note Added: 0003378
2005-01-06 18:21 cbradney Note Added: 0003379
2005-01-06 18:22 cbradney Status assigned => resolved
2005-01-06 18:22 cbradney Fixed in Version => 1.2.1cvs
2005-01-06 18:22 cbradney Resolution open => fixed
2005-01-06 18:23 cbradney Status resolved => closed
2005-01-06 19:28 mhanski Relationship added related to 0001389
2005-01-11 16:42 mhanski Relationship added related to 0001537
2006-04-11 08:52 mhanski Relationship added related to 0003622