Giters

dasm-assembler / dasm

Macro assembler with support for several 8-bit microprocessors

Home Page:https://dasm-assembler.github.io/

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Documentation - recent additions - my thoughts

andrew-davie opened this issue · comments

commented

After going something like 30 years with just a simple text file for documentation... a couple of months ago I embarked on a mammoth effort ;P to create a somewhat decent PDF manual for DASM. I'm delighted to see new additions to DASM, and expecially from new contributors.

I am a bit concerned that we're heading away from the basic intent of the PDF -- and that is, a single, central place for documentation. The recent commits include a separate HTML file of documentation, and it appears a "tex" file for inclusion which will be a completely different style/layout to the existing documentation.

I guess contributors are between a rock and a hard place with this. How to sufficiently document your stuff if you don't know how to (or don't want to) modify the existing manual.

The other thing of slight concern to me is the new "man" page, which has sole copyright to the contributor. Personally I would like to see copyright of things included in DASM as being to the DASM team, not individuals. We did the individual copyrights yonks ago, and you just end up with a long list of names and dates and copyrights - and even forks which try to claim past copyright on previous peoples' works. So the copyright thing is a bit of a concern to me, too.

So, two issues I'd like to see others' thoughts on...

  1. New documentation presented as HTML and TEX include file
  2. copyright notices on contributions from individuals.
commented

Hello Andrew, I did the recently check-in html and tex files. But I did this to my fork of dasm. There is no need to merge them upstream.

I agree completly. Of course the main central sources of documentation should be the tex files.

I tried to create a tex file for inclusion into the main documentation but I'm not so skilled with tex. So I used my spreadsheet program to color some cells and exported in tex format as a Q&D approach. However I didnt work for me either. My latex installation is missing some styles and furthermore the coloring is lost in the final output. Also the page should be in landscape format and I hadn't succes with this also.

I included the HTML file in the commit just to display how it should look like. It might be deleted later. I need some ideas/hints to rework this.

commented

My thoughts on this:

  • I don't think we need a specific man page showing the DASM arguments. Just running dasm without any arguments will show you this already. Also, the individual copyrights in the man page is a no-go. I will write a comment and probably close this pull request.
  • The 68hc908 opcode summary html looks like it was generated with a tool, so I don't think it matches the current TeX documentation. ....I'm just reading thomas374b's reply, and it looks like he didn't meant to include these documentation-files to his pull request. I'll reply to thomas374b's pull request and explain how pull requests should be done to prevent this.
commented

I've opened a new pull request #103 with proper branching

commented

The two issues that Andrew had with the additions in documentation were solved, so I'm closing this issue.