bugFreeciv - Bugs: bug #22796, freeciv-manual output is messy and...

 
 
Show feedback again

bug #22796: freeciv-manual output is messy and inconsistent

Submitted by:  Frank <dunnoob>
Submitted on:  Sun Oct 12 22:25:11 2014  
 
Category: generalSeverity: 1 - Wish
Priority: 1 - LaterStatus: None
Assigned to: NoneOpen/Closed: Open
Release: 2.5.0-beta1Operating System: None
Planned Release: Contains string changes: None

Add a New Comment (Rich MarkupRich Markup):
   

You are not logged in

Please log in, so followups can be emailed to you.

 

(Jump to the original submission Jump to the original submission)

Sat Aug 15 14:17:23 2015, comment #14:

Remaining issues of this ticket boil down to lack of polish for freeciv-manual. Since I don't think anyone has plans to put in substantial work on that, removing release target.

Comment #2:
# was bug #22869
# was bug #22347
# messiness by design
# messiness by design

Comment #6: not reproduced, assumed moot now given fix for bug #22347.

Jacob Nevins <jtn>
Project Administrator
Sun Aug 9 19:18:19 2015, comment #13:

Patch #6214 adds support to select formatting of the produced manuals freeciv configure time, but starting only from 2.6.

Marko Lindqvist <cazfi>
Project Administrator
Wed Jan 21 00:54:50 2015, comment #12:

This ticket is messy - parts have been fixed in other tickets, and other parts are not well defined. Anyway, improvements to freeciv-manual are not 2.5.0 blocker, so setting target to sort this out to 2.5.1

Marko Lindqvist <cazfi>
Project Administrator
Sun Dec 7 17:06:23 2014, comment #11:

We have a patch #5445 about not distributing freeciv-manual to end users at all in Windows Installer packages. I've postponed committing it in the light of this discussion that someone might actually want to use it. Please comment to that ticket if you have an opinion about the matter.

Marko Lindqvist <cazfi>
Project Administrator
Mon Dec 1 06:55:53 2014, comment #10:

Hi, I only copied + pasted the English output as is, for beta2 it required one minor manual tweak (as for 2.4.3 and beta1 near the "cancelvote" section header, maybe it's a bug and not only a copy + paste issue on my side.)

Of course I could also try that for a different ruleset, but apparently the manual tool uses parts of the same code as the GTK client help menu: If the latter works for "alien" it should be also okay for the manual tool.

Maybe I'll test the effect for "experimental", it should show the hospital (or rather a red link for this missing image on the wiki.)

Frank <dunnoob>
Tue Nov 25 05:52:10 2014, comment #9:

> I posted the output


If you're interested on working on this, I would really appreciate someone setting wikipages up for different rulesets.

civ2civ3 is quite different from classic ruleset, included in main freeciv distribution in freeciv-2.5 and freeciv-2.6, and is about to become the default ruleset in 3.0 (we'd want the default ruleset documented, wouldn't we?)

I've started manual work for documenting alien ruleset as I had no clear idea how to setup things with freeciv-modpack. This could be made correctly instead. Alien ruleset is currently distributed as custom ruleset (though development takes place in freeciv repository), but future version of freeciv (hopefully 3.0) should have it included.

Marko Lindqvist <cazfi>
Project Administrator
Sat Oct 25 21:57:15 2014, comment #8:

I posted the output for 2.4.3 and 2.5.0-beta1 as subpages of http://freeciv.wikia.com/wiki/Freeciv-manual

Three missing images (lake, floor, coastal) added to the Wiki. Bug linked in the (incomplete) 3rd part for 2.5.0-beta1.

Frank <dunnoob>
Sat Oct 25 15:35:55 2014, comment #7:

> 1. freeciv-manual -h lists -- --help as GUI help option.
> freeciv-manual -- --help fails with "unknown option --".

I will commit your patch under bug #22869.

> New observation: Part 4 (buildings) is not empty for LANG=C
> (instead of auto de on my box). The output ends after "Barracks"

I couldn't reproduce this with latest S2_5 code, even with LANGUAGE=de.

>> Otherwise, freeciv-manual is unloved and unlikely to receive
>> much maintenance. The strange mixture of Mediawiki and HTML
>> is kinda by design, ish.
> Okay, but I don't get the "by design" idea. If folks want
> manual pages for a specific ruleset, they would need a
> browser (and the PNGs) for the -dUSE_HTML variant of the manual.

What I mean is that freeciv-manual isn't really for "folks", it's a helper for us Freeciv maintainers to maintain our own wiki (although as you'll have noticed, we haven't even been doing that). I occasionally use it for other things like reviewing the effects of a change to the help system in bulk (which is where the messy government help came from).

For it to be a credible user-facing tool, we'd want to make it more complete, make USE_HTML a runtime option, etc; so far no-one's had the spare effort or inclination. I've raised patch #5388 to document this more obviously.

Jacob Nevins <jtn>
Project Administrator
Fri Oct 17 00:36:46 2014, comment #6:

New observation: Part 4 (buildings) is not empty for LANG=C (instead of auto de on my box). The output ends after "Barracks", I created ten test pages up to the 2.5.0-beta1 buildings.

Frank <dunnoob>
Sun Oct 12 23:37:02 2014, comment #5:

Okay, but I don't get the "by design" idea. If folks want manual pages for a specific ruleset, they would need a browser (and the PNGs) for the -dUSE_HTML variant of the manual.

The shipped variant, where USE_HTML was not defined at compile time, apparently requires a Wiki (and the PNGs).

Frank <dunnoob>
Sun Oct 12 23:20:14 2014, comment #4:

The giant pile of assertion failures is already fixed in svn in bug #22347.

Otherwise, freeciv-manual is unloved and unlikely to receive much maintenance. The strange mixture of Mediawiki and HTML is kinda by design, ish.

Jacob Nevins <jtn>
Project Administrator
Sun Oct 12 23:03:26 2014, comment #3:

Fourth attempt for sr #3178, the 2nd of five items was corrupted:

Frank <dunnoob>
Sun Oct 12 22:33:43 2014, comment #2:

Third attempt:

  1. freeciv-manual -h lists -- --help as GUI help option. freeciv-manual -- --help fails with "unknown option --".
  2. freeciv-manual -d 3 -l deleteme.log reports that the dead or long loop begins immediately after MANUAL_TERRAIN for MANUAL_BUILDINGS; manual4.html is created, but empty.
  3. The manual parts 1..3 consist of some odd mixture of HTML and MediaWiki markup (no USE_HTML in civmanual.c line 83). No new bug, that was already odd for 2.3/2.4.
  4. Ignoring the Wiki markup the manual parts 1+2 (all server commands+options) are fine, and ignoring the missing PNGs parts 3..5 were also interesting in 2.3/2.4. But part 6 (MANUAL_GOV) is messy. There is a "FIXME" in line 472 for MANUAL_GOV.

Suggested fix for (1) after looking in common/fc_cmdhelp.h, replace the 2nd TRUE by FALSE in tools/civmanual.c line 617:

Frank <dunnoob>
Sun Oct 12 22:28:18 2014, comment #1:

So far for UIs without "preview", entering my own "submit until readable" dead loop now:

  1. freeciv-manual -h lists -- --help as GUI help option. freeciv-manual -- --help fails with "unknown option --".
  2. freeciv-manual ends up in a dead loop or very long loop of assertion failures. <verbatim>

in is_nation_pickable() [../../../../common/nation.c::206]:
assertion '!is_server()' failed. </verbatim>

  1. freeciv-manual -d 3 -l deleteme.log reports that the dead or long loop begins immediately after MANUAL_TERRAIN for MANUAL_BUILDINGS; manual4.html is created, but empty.
  2. The manual parts 1..3 consist of some odd mixture of HTML and MediaWiki markup (no USE_HTML in civmanual.c line 83). No new bug, that was already odd for 2.3/2.4.
  3. Ignoring the Wiki markup the manual parts 1+2 (all server commands+options) are fine, and ignoring the missing PNGs parts 3..5 were also interesting in 2.3/2.4. But part 6 (MANUAL_GOV) is messy. There is a "FIXME" in line 472 for MANUAL_GOV.

Suggested fix for (1) after looking in common/fc_cmdhelp.h, replace the 2nd TRUE by FALSE in tools/civmanual.c line 617:
<verbatim>
- cmdhelp_display(help, TRUE, TRUE, TRUE);
+ cmdhelp_display(help, TRUE, FALSE, TRUE);
</verbatim>

Frank <dunnoob>
Sun Oct 12 22:25:11 2014, original submission:
  1. freeciv-manual -h lists -- --help as GUI help option.

freeciv-manual -- --help fails with "unknown option --".

  1. freeciv-manual ends up in a dead loop or very long loop

of assertion failures. <verbatim>
in is_nation_pickable() [../../../../common/nation.c::206]:
assertion '!is_server()' failed. </verbatim>

  1. freeciv-manual -d 3 -l deleteme.log reports that the dead

or long loop begins immediately after MANUAL_TERRAIN for
MANUAL_BUILDINGS; manual4.html is created, but empty.

  1. The manual parts 1..3 consist of some odd mixture of HTML

and MediaWiki markup (no USE_HTML in civmanual.c line 83).
No new bug, that was already odd for 2.3/2.4.

  1. Ignoring the Wiki markup the manual parts 1+2 (all server

commands+options) are fine, and ignoring the missing PNGs
parts 3..5 were also interesting in 2.3/2.4. But part 6
(MANUAL_GOV) is messy. There is a "FIXME" in line 472 for
MANUAL_GOV.

Suggested fix for (1) after looking in common/fc_cmdhelp.h,
replace the 2nd TRUE by FALSE in tools/civmanual.c line 617:
<verbatim>
- cmdhelp_display(help, TRUE, TRUE, TRUE);
+ cmdhelp_display(help, TRUE, FALSE, TRUE);
</verbatim>

Frank <dunnoob>

 

(Note: upload size limit is set to 1024 kB, after insertion of the required escape characters.)

Attach File(s):
   
   
Comment:
   

No files currently attached

 

Digest:
   bug dependencies.

Items that depend on this one: None found

 

Carbon-Copy List
  • -unavailable- added by cazfi (Posted a comment)
  • -unavailable- added by pepeto (Updated the item)
  • -unavailable- added by jtn (Posted a comment)
  • -unavailable- added by dunnoob (Submitted the item)
  •  

    Do you think this task is very important?
    If so, you can click here to add your encouragement to it.
    This task has 0 encouragements so far.

    Only logged-in users can vote.

     

    Error: not logged in

     

     

    Follow 9 latest changes.

    Date Changed By Updated Field Previous Value => Replaced By
    Sat Aug 15 14:17:23 2015jtnSeverity3 - Normal=>1 - Wish
      Priority5 - Normal=>1 - Later
      Planned Release2.5.1, 2.6.0=>
      Summaryfreeciv-manual 2.5.0-beta1 bugs=>freeciv-manual output is messy and inconsistent
    Wed Jan 21 00:54:50 2015cazfiCategoryNone=>general
      Planned Release2.5.0, 2.6.0=>2.5.1, 2.6.0
    Sat Oct 25 15:13:23 2014jtnDependencies-=>Depends on bugs #22347
    Sat Oct 25 15:13:11 2014jtnDependencies-=>Depends on bugs #22869
    Wed Oct 22 07:31:50 2014pepetoPlanned Release=>2.5.0, 2.6.0
    Show feedback again

    Back to the top


    Powered by Savane 3.1-cleanup