Software documentation.

Hello, All The topic was created to discuss or publish possible ways to create software documentation using software tools available for ZX-Spectrum. We can also talk about cross-platform solutions.

Hello, CityAceE Cit> I want to comment not on the content of the documentation, but on its form. I'm for Cit> to create and use documentation in HTML format and Cit> Spectrum, and on the PC, that is, have a single format. Cit> First, is there a final form of representation prepared for publication option, or form used when typing? They may vary. I can say HTML for initial input of any texts practically unusable for human writing. Just how the final form of the HTML representation is of interest because obvious reasons (almost everywhere you can view and print, more or less easily converted into another form). > Such documentation uses a minimum of tags, so create > corresponding viewer that will support this minimum at all > not difficult! > Why HTML is unsuitable: it does not allow you to somehow clearly structure the text in on a more global level than dividing into elements such as headings, paragraphs, lists etc. This in turn makes it impossible to number sections text, the ability to implement hyperlinks to a specific elementtext (exactly so, no matter how absurd it may sound - HTML will not allow, for example, refer to section 1.2 or a section with such and such a name, only to a specific point in the text), it is difficult to implement footnotes, floating comments and other elements. Plus difficulties with typing formulas (MathML is not supported everywhere...) And difficulties in obtaining high-quality illustrations suitable for viewing, and for printing. Get high-quality formatted HTML suitable for Printing text is generally almost impossible. The only method I know is html2ps only produces text of satisfactory quality (while LaTeX is excellent). Print the same text from the typical browser such as IE or Mozilla without tricks in general it is practically impossible: it will come to the point that even drawings and the tables will tear in the middle of the page. I view HTML solely as a convenient means of presentation. screen, nothing more. > (By the way, why not create such a viewer within the ZX SDK?) For that > the benefits are obvious! Such documentation will be equally easy > watch both on the Spectrum and on the PC under different OS, and if necessary > and print with high quality. Does it make sense to rely on HTML? In fact you need: * hypertext representation (not necessarily HTML!);* it is desirable to be able to represent elements text not representable in a plain-text file, for example, additional characters, superscripts and subscripts, different fonts and colors - I say preferably, but not necessarily; * Illustrations are preferred. Came across the electronic press for ZX-Spectrum copies supporting the first and third points. And there was back in the day, long ago (~2000), a program, either frame maker, or paper maker - for creating an electronic "newspaper" for ZX-Spectrum. The program is Spectrum, not pisish. Here her viewer is also quite good. Another thing is that to prepare such documentation, without titanic efforts, exclusively on the Spectrum is impossible... And one more thing. A significant part of the documentation is reviewed directly while writing code. This means that it can be viewed will be in the built-in assembler editor. Therefore, it must support such a "format". It would be it would be great if ALCO added “two-window” functionality to Alasm (when the screen is vertically divided into two windows), color support codes from ACEdit, hyperlink support and insertion support pictures. Most likely, it will turn out to be a hybrid of ACEdit and ALASM. It would be great.

Hello fk0 Regarding the implementation of documentation in the program text, everyone should look at JavaDOC and from its consequences (PHPDOC, Summary in .NET). The point is that there are certain “tags” between which there is text documentation, and then special software processes the program text into dock generation item. For example: ; /// [DOC] ; /// PRINTCHAR - prints a character to the stream ; /// from register A PRINTCHAR RST #10 RET Almost every Speck assembler supports export to text. and the text Processing is not a big deal. If you properly configure the generic, you can not limit yourself to assembler // /// [DOC] // /// example void example(void) {} /* /// [DOC] /// example2 */ void example2(void) {} 1) no need to go crazy with DOC_MODE 2) the documentation is not divorced from the program text (i.e. you can write an awesome generic that, in addition to tearing out docks, will also paint and format program text

Hello fk0 I want to speak not on the content of the documentation, but on its form. I'm in favor of create and use documentation in HTML format both on the Spectrum and on the PC, that is, have a uniform format. Such documentation uses a minimum tags, so create an appropriate viewer that will support this at least it’s not difficult at all! (By the way, why not create such a viewer within ZX SDK?) The benefits are obvious! Such documentation can be equally easily watch both on the Spectrum and on the PC under different OS, and if necessary, high quality print.

Hello fk0 fk0> It would be fk0> it would be great if ALCO added “two-window” to Alasm fk0> (when the screen is vertically divided into two windows), color support fk0> codes from ACEdit, hyperlink support and insertion support fk0> pictures. Most likely, it will turn out to be a hybrid of ACEdit and ALASM. It would be fk0> great. ALSM is supplied not only for 8, but also for 7-pixel lines, where support You can’t insert flowers and pictures. Yes, and I think there are big problems with color codes - The text is tokenized! comments also have their own format PS look at my QHTV program. it was originally made for viewing documentation. there is everything you need and don't need. the only serious limitation I see the text size. I will work on this.

Hello,GriV regarding the final form - no tags are needed inside the program text - they They will just get in the way and give very “intelligent” homos a reason to do some nonsense invent. And what can you then convert the doc received from the parser into? It's everyone's personal business.

Hello Vitamin 2fk0> the self-documentation system is generally cool, but I don’t understand how it works 2fk0> details - the code and the program itself are mixed (when generated), but this is not 2fk0> the most important. Regarding editing/viewing - it's really easy to do comments - through the same curved strokes (symbols "") semicolons (";") and well etc. - the editor itself will have two sliding windows - one on top of the other - when the programmer moves the cursor in the adjacent window it is automatically loaded (or simply displayed when it is in memory) comment on the specified line of text asma. Moreover, during physical unloading on the disk, the text will consist of assembler lines mixed with help lines, and when the text is edited program, it is transparent to the programmer - in the next window he has these comments. With finite existing code, you can also get clean code without any questions or pure text - again through a parser. I support the idea, I give 5 points (-;