manual building/conversion

Started by Alberth, Thu 17/07/2014 17:21:05

Previous topic - Next topic

Alberth

Hello,

I downloaded the source, and am trying to build the manual at my Fedora system, and ran into a little trouble. This seems the least wrong forum to ask about it.

- My first attempt was to run "pdflatex" on it, as it was a .tex file. My compiler complains it's old (2.09 source, rather than the 2e variant, which exists for around a decade already or so). Also, it's not compilable, A number of small edits brought me to page 81, where I ran into a bigger problem with a "description" list. I can probably fix that too, but I need to check with the book. Quickly looking at the result showed at least one table that was waaaaay too wide, at which point I decided this would be more work.

- My second attempt today was to use the official way, as listed in "ccompile_documentation_unix.sh". I installed the various wx* packages, and ran the script, which results in a long list of compile errors while building tex2rtf

Code: cpp
g++ -c `wx-config --cxxflags`  -o rtfutils.o rtfutils.cpp
tex2any.cpp: In function 'bool read_a_line(wxChar*)':
tex2any.cpp:454:39: error: invalid cast from type 'wxCStrData' to type 'wxChar* {aka wchar_t*}'
        OnError((wxChar *)errBuf.c_str());
                                       ^
(omitted a lot of similar errors) and
Code: cpp
rtfutils.cpp: In function 'bool WriteHPJ(const wxString&)':
rtfutils.cpp:541:19: warning: deprecated conversion from string constant to 'wxChar* {aka wchar_t*}' [-Wwrite-strings]
         helpTitle = _T("Untitled");
(also omitted a lot of similar warnings).
These problems happen in a number of variations.

While it looks solvable (now idea how currently, never done anything with wxwidgets), the end-goal seems to be html pages.
This brings me to the 3rd option.

- Convert the .tex file to .rst (restructured text). http://docutils.sourceforge.net/rst.html or for multi-file documents/sites perhaps even Sphinx http://sphinx-doc.org/tutorial.html this is a layer on top of rst, with additional goodies, and cross-document references.

I can do any of the above three, but I don't know what is actually wanted.

BigMc

That file was written for tex2rtf which uses its own TeX dialect as far as I can tell. That this is not optimal is reflected in the fact that it became hard to find tex2rtf anywhere except the copy which is included with wxwidgets. The html files were used for a Windows help file. tex2rtf should also be able to produce a rtf file if you prefer that.

Alberth

#2
Well, yeah, but tex2rtf fails to build at my system as I pointed out at item 2 in my first post, due to a too new g++ or a too new wxwidgets probably. Fedora typically picks very new versions of the software.

Are you saying you want to stick with tex2rtf?

Edit: I made a quick and dirty partial conversion of the manual to Sphinx: https://github.com/Alberth289346/ags/commit/f44fc381b7c1d54653ab6493f93cbb295b81fe4a

Files that I touched:
Code: ags
other-features.rst
 credits.rst
tutorial.rst
runtime-engine.rst
introduction.rst
copyright.rst
ags.rst

Note that github also knows restructured text, so it can display the files somewhat nicely. It doesn't do the Sphinx extensions, so you'll at least miss the cross-document references.
If you checkout the commit, there are also generated html files, _build/html/ags.html is the starting point.
I'd be happy to do the entire conversion if that is desired.

BigMc

You could do a pull request to get the discussion started on github.

Crimson Wizard

Wait a moment... can someone elaborate, please: is this about completely changing the manual source format?
Will that in any way conflict with the process of creating Windows help file?

BigMc

Yes it changes the manual source format. I don't know if Sphinx is the best choice but changing to a standard format sounds like a good idea.

Crimson Wizard

#6
Okay, I see. Frankly I haven't heard about this "Sphinx", so I just didn't know what is it all about.
If I am not mistaken, this is it:
http://sphinx-doc.org/

This sounds interesting, but I suggest we test first to see how this works for our purposes.

Alberth

#7
By all means try it. That's why I did a quick and dirty partial conversion.

Restructured text is the basis. It is an ASCII text format, where you can express markup, links etc, a bit like todays Wiki languages, but it's way older. Restructured text is aimed at single file short documents, like enhancement proposals (eg Python PEPs). There is tooling to convert to various output formats.
Sphinx is an extension on top of restructured text. It is aimed at making larger documentation sites. For example, docs.python.org is built with it entirely. Html is of course an important output format, but it has other formats too. It provides a search box for the site as well. You can further customize the generated output with themes and CSS stuff (which I have no clue about, but I know it's possible).

I only have a Linux system, so my options for experimenting with documentation are limited, beyond "it works in my browser".
However, if I can be of further assistance, please let me know.

Edit: Created a proper conversion and a PR: https://github.com/adventuregamestudio/ags/pull/173

Crimson Wizard

I'll check how this works soon.

BTW, can we try if that's possible to create an automated tool chain which will compile manual from github into HTML and replace one on the AGS website here: http://www.adventuregamestudio.co.uk/manual/ ?
This way developers may edit the manual and site admins update the online manual contents easily.

Alberth

The Sphinx quickstart program generates a Makefile or make.bat, which is why I added those to the PR. It's overkill in production, in the end it just runs a single sphinx command, which you can of course also directly execute.
Sphinx itself is written in Python afaik, so it should run at a system where Python is installed (no doubt Sphinx comes with install instructions, I didn't check, as my package manager provided it.

The other steps sounds doable too, although I wouldn't know how to pull a file from GH directly (I'd clone the git repository to the local machine instead). Uploading the result I would do with ssh.
A simple shell script may be enough. On the other hand, since you have Python installed anyway, a Python solution would also be feasible I guess.

SMF spam blocked by CleanTalk