Re: [Nasm-devel] On the future of the NASM documentation

[Ed B. <be...@mi...>]

On 04/14/2017 01:32 PM, H. Peter Anvin wrote:

> In the meantime I did some work to make both the PDF and HTML
> documentation look quite a bit nicer.
> 
> Opinions appreciated...

I wrote this back in 2001, almost exactly 16 years ago and still agree 
with myself.  :)  Interestingly, the tool that was called "Buttress" 
back then, and not finished, has long since been completed and renamed 
"halibut".  Could be an option?  I haven't looked at it in any detail.


> To: nas...@ya...
> From: Ed Beroset <be...@mi...>
> Subject: Re: [nasm-devel] RDSRC.PL of Netwide Assembler
> 
> At 15:11 3/19/01 -0500, you wrote:
> Robert Riebisch wrote:
> 
>>>> I am looking for someone who would be so kind to modify RDSRC.PL (from
>>>> the Netwide Assembler source code distribution archive) "a little
>>>> bit".
>>>
>>>You might want to look at what Simon has to say about rdsrc.pl:
>>>
>>>http://www.chiark.greenend.org.uk/~sgtatham/buttress.html
>>>
>> Unfortunately, Buttress seems to be just "vaporware", but Simon seems to
>> think rdsrc.pl is *not* the way to go. Perhaps someone *really* good at
>> Perl could do something with it.
> 
> I'm good with Perl, but I don't see the need for Yet Another Documentation Tool.  If somebody needs or wants the document in something other than the currently supported six different formats, does this really require a special NASM tool?  Why not use one of those six formats as input to some more general purpose tool?
> 
> If I were the king of the world, I'd turn the *source* document into XML and then simply use XSLT to transform into whatever other hundred formats were desired.  There are already tools for this kind of thing -- why reinvent the wheel? 
> 
>>Here is my "to do" list:
>>...
>>8. Read over the source, and create documentation that reflects what the
>>damn thing *actually* does...
> There's a relatively easy way to do that, which I would highly recommend:  
> http://www.stack.nl/~dimitri/doxygen/
> 
>> 9. World Peace? Naw, that would *really* be overkill..
> 
> Technically, that would be "underkill."  ;-)
> 
> Ed