Angband.oook.cz
Angband.oook.cz
AboutVariantsLadderForumCompetitionComicScreenshotsFunniesLinks

Go Back   Angband Forums > Angband > Vanilla

Reply
 
Thread Tools Display Modes
Old August 18, 2011, 01:43   #81
d_m
Angband Devteam member
 
d_m's Avatar
 
Join Date: Aug 2008
Location: Philadelphia, PA, USA
Age: 41
Posts: 1,516
d_m is on a distinguished road
That said, I also have a soft spot for LaTeX, so I am fine with that choice as well. I mostly just hate writing HTML.

I'd also be OK with one of the other "plaintext-esque" markup languages. I just know that RST has gotten a lot of use and is pretty flexible/powerful.
__________________
linux->xterm->screen->pmacs
d_m is offline   Reply With Quote
Old August 18, 2011, 08:08   #82
CJNyfalt
Swordsman
 
Join Date: May 2007
Posts: 289
CJNyfalt is on a distinguished road
RST looks interesting and easy.
I have used LaTeX in the past and liked it.
I have tried Docbook and I hated it for having too verbose tags.
HTML has problems with formating and indexing, and also use the same clumsy type of tagging as Docbook.
There is also troff, texinfo and POD, but I have no experience at all about them. From what I have read the first two is not what we are looking for, unless we want to create a man-page. I know next to nothing about POD.
CJNyfalt is offline   Reply With Quote
Old August 18, 2011, 15:26   #83
d_m
Angband Devteam member
 
d_m's Avatar
 
Join Date: Aug 2008
Location: Philadelphia, PA, USA
Age: 41
Posts: 1,516
d_m is on a distinguished road
Quote:
Originally Posted by CJNyfalt View Post
RST looks interesting and easy.
I have used LaTeX in the past and liked it.
I have tried Docbook and I hated it for having too verbose tags.
HTML has problems with formating and indexing, and also use the same clumsy type of tagging as Docbook.
There is also troff, texinfo and POD, but I have no experience at all about them. From what I have read the first two is not what we are looking for, unless we want to create a man-page. I know next to nothing about POD.
I've written troff and it's neat in a crufty way but not something I'd want to maintain. I used POD at a previous job writing Perl and despise it as a format.

I haven't used texinfo at all, nor docbook.

EDIT: The other formats I expected people to bring up (maybe) were Markdown and Asciidoc, which are similar to (and come after) RST.
__________________
linux->xterm->screen->pmacs
d_m is offline   Reply With Quote
Old August 21, 2011, 20:32   #84
fph
Knight
 
Join Date: Apr 2009
Location: Pisa / DL0
Posts: 988
fph is on a distinguished road
I started rewriting the docs in RST. After a hands-on experience, I see only some minor problems. I am listing them here:
-funny unexpected side-effect: when RST reads "*slay* dragons", it thinks you want to put the word "slay" in italics. I think we can work around this without making the .txt unclear by using a suitably crafted CSS that inserts back *...* before and after every <em></em> tag. Yes, that's a ugly hack.
-it's not clear to me how to link to a specific section of another document (e.g., link to a section in commands.txt from dungeon.txt)
-a couple of constructs look strange when read directly in the .txt. For instance, links with "_" at the end. People reading the .txt help files would have to get used to "some things looking strange".
-in the command descriptions, we have (``right-paren``) (where ``text`` means "typeset the text in monospace). I'd like to replace "right-paren" with the symbol, but this seems to be impossible in RST.

On a conference this week, but looking forward to finishing soon (if you don't tell me to stop, of course ).
__________________
Dive fast, die young, leave a high-CHA corpse.
--
You read a scroll labeled 'lol gtfo' of Teleport Level.
fph is offline   Reply With Quote
Old August 22, 2011, 10:15   #85
Magnate
Angband Devteam member
 
Join Date: May 2007
Location: London, UK
Posts: 5,060
Magnate is on a distinguished road
Send a message via MSN to Magnate Send a message via Yahoo to Magnate
Quote:
Originally Posted by fph View Post
I started rewriting the docs in RST. After a hands-on experience, I see only some minor problems. I am listing them here:
-funny unexpected side-effect: when RST reads "*slay* dragons", it thinks you want to put the word "slay" in italics. I think we can work around this without making the .txt unclear by using a suitably crafted CSS that inserts back *...* before and after every <em></em> tag. Yes, that's a ugly hack.
-it's not clear to me how to link to a specific section of another document (e.g., link to a section in commands.txt from dungeon.txt)
-a couple of constructs look strange when read directly in the .txt. For instance, links with "_" at the end. People reading the .txt help files would have to get used to "some things looking strange".
-in the command descriptions, we have (``right-paren``) (where ``text`` means "typeset the text in monospace). I'd like to replace "right-paren" with the symbol, but this seems to be impossible in RST.

On a conference this week, but looking forward to finishing soon (if you don't tell me to stop, of course ).
Not at all - thanks for the effort! I'm not familiar with RST so I hope d_m will be able to answer your points better than I can, but I do think we could happily replace "*slay*" with "kill" or "execute" or "..'s bane" or whatever. I don't think we desperately need to stick with *slay*.

I don't think I understand the third point - could you give us an example of a link with _ at the end?
__________________
"3.4 is much better than 3.1, 3.2 or 3.3. It still is easier than 3.0.9, but it is more convenient to play without being ridiculously easy, so it is my new favorite of the versions." - Timo Pietila
Magnate is offline   Reply With Quote
Old August 22, 2011, 12:02   #86
CJNyfalt
Swordsman
 
Join Date: May 2007
Posts: 289
CJNyfalt is on a distinguished road
Quote:
Originally Posted by Magnate View Post
..., but I do think we could happily replace "*slay*" with "kill" or "execute" or "..'s bane" or whatever. I don't think we desperately need to stick with *slay*.
I was going to suggest to use bold instead of italics, but renaming is an even better solution.
CJNyfalt is offline   Reply With Quote
Old August 22, 2011, 15:09   #87
EpicMan
Swordsman
 
Join Date: Dec 2009
Location: Dallas, Texas, USA
Posts: 436
EpicMan is on a distinguished road
Can't you just escape the asterisks in the docs ("\*")?
EpicMan is offline   Reply With Quote
Old August 22, 2011, 16:38   #88
fph
Knight
 
Join Date: Apr 2009
Location: Pisa / DL0
Posts: 988
fph is on a distinguished road
Yes, I can, but the problem here is that we want two things at the same time:
-the .txt should look good, so that it can be used in the online help without further munging
-the .txt should be a valid RST document that can be converted to a good-looking HTML/PDF.
You cannot achieve the two goals at the same time for "*slay*".
__________________
Dive fast, die young, leave a high-CHA corpse.
--
You read a scroll labeled 'lol gtfo' of Teleport Level.
fph is offline   Reply With Quote
Old August 22, 2011, 19:36   #89
d_m
Angband Devteam member
 
d_m's Avatar
 
Join Date: Aug 2008
Location: Philadelphia, PA, USA
Age: 41
Posts: 1,516
d_m is on a distinguished road
Quote:
Originally Posted by fph View Post
Yes, I can, but the problem here is that we want two things at the same time:
-the .txt should look good, so that it can be used in the online help without further munging
-the .txt should be a valid RST document that can be converted to a good-looking HTML/PDF.
You cannot achieve the two goals at the same time for "*slay*".
Yes, fph is totally right about this.

Unfortunately all of the modern plaintext markup systems are going to have this problem I think.

If we're willing to forgo italics/bold then I could imagine a (very simple) transformation script from the plaintext into valid RST that escapes *. Maybe this is a terrible idea though?

We could do what Magnate suggested, although I'm reluctant for our doc format to control how we talk about the content!

What do you all think? fph as the person working on this now I'm especially interested in your opinion.
__________________
linux->xterm->screen->pmacs
d_m is offline   Reply With Quote
Old August 22, 2011, 20:00   #90
Magnate
Angband Devteam member
 
Join Date: May 2007
Location: London, UK
Posts: 5,060
Magnate is on a distinguished road
Send a message via MSN to Magnate Send a message via Yahoo to Magnate
Quote:
Originally Posted by d_m View Post
We could do what Magnate suggested, although I'm reluctant for our doc format to control how we talk about the content!
Just to say that as a general rule I agree with this 100%, but *slay* is something I've been wanting to re-name for years ....

Just sayin'.
__________________
"3.4 is much better than 3.1, 3.2 or 3.3. It still is easier than 3.0.9, but it is more convenient to play without being ridiculously easy, so it is my new favorite of the versions." - Timo Pietila
Magnate is offline   Reply With Quote
Reply


Currently Active Users Viewing This Thread: 1 (0 members and 1 guests)
 
Thread Tools
Display Modes

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off

Forum Jump

Similar Threads
Thread Thread Starter Forum Replies Last Post
Reviving Iso-Angband, an isometric view addon for Angband Hajo Development 111 August 3, 2014 19:44


All times are GMT +1. The time now is 23:30.


Powered by vBulletin® Version 3.8.11
Copyright ©2000 - 2021, vBulletin Solutions Inc.