Hello to all interested in improving the Quex documentation,
We're happy to have you. I have started this thread to coordinate our efforts to improve the Quex docs. The doc improvement project has just begun, so there is still a lot to do.
Currently, we are going over the current text and making minor edits (fixing spelling and grammar problems for instance). Below is a list of the txt files found in the quex docs.
I have placed an 'X' next to the files that have been lightly edited by me.
To those interested in joining, I ask you to read through the txt files to get a feel for what Quex can do. I would also ask that you post here which files you would like to edit.
Once these files have been edited, we will discuss the bigger changes that need to be made (format, style, order).
As you suggested, I will take up reviewing of files
from "quex/formal/generated-class/constructor-extension.txt" to
"quex/inside-quex/hopcroft-optimization.txt". Henceforth, I will be using letter 'M' before all the files that I review.
As I am a newbie to 'Open Source', I request you to guide me through the process and inform me about the intricacies involved.
Regards,
Malathi Voodi
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
please, do not consider any current state of the buffer handling API as it is currently documented. There has been major changes which are not included in the documentation. The question is: Can anyone figure out the design from the code,
or shall I better write a draft.
Would anyone be interested in setting up a Doxygene Environment for the
documentation of the 'code_base/' directory's code?
Regards
Frank
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Doxygen looks interesting and I'd like to figure it out, but I've gotten a little behind on the txt edits.
Malathi, if you'd like to extract the buffer handling documentation using Doxygen, go ahead.
Otherwise, if I finish up in the next couple of days and nobody else has volunteered to do it, I'll see if I can figure it out, since it doesn't seem too complicated (at least the concept, implementation is probably a different story).
I just got an ethernet connection (as opposed to wireless) again, since I just moved, and I fear that configuring my FreeBSD mediaserver has distracted me.
Martin
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
After some delay, I have finished the preliminary edits of the txt files. Malathi finished his some time ago, and once I have received his edited files I will create the new PDF, which can be used until the next revision of the documentation is ready.
Still to do:
generate buffer handling documentation using doxygen
change user-defined token class docs to reflect Frank's email:
"The token ids are by default placed in the global namespace and the
default token prefix is "QUEX_TKN_".
This happens as a conclusion to the issue described in bug report
2136054.
The new behavior may also have import on the documentation for 'user
defined token classes'."
Perform any major revision to sections that remain unclear after the minor edits have been completed. This would also include other remaining issues such as standardized spelling and capitalization.
For the major edits, I suggest that Malathi edit the files that I edited in the first round, and vice-versa. Anybody wishing to join (and I encourage you to) can volunteer and a portion of the editing will be given to him.
Any issues that come up while doing these major edits can be posted here for discussion.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
I just read the access restriction documentation and it says that there is no per-path access restriction possible. Thus, we might be better off with a 'ping-pong' procedure, where you send me the docuementation as soon as you have something not necessarily perfect. I can then do my changes, add a note, and send it back. What do you think?
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
I was wondering about svn access myself. An alternative would to use another web-storage option for modifying the documentation amongst ourselves. Are you familiar with Dropbox (http://www.getdropbox.com/)? It's a web-storage/collaboration app that will allow us to synch our versions of the documentation in, essentially, real time. I created a symbolic link to my quex directory in the Dropbox folder that was created. Once you receive my email granting access you should be able to easily view and comment on my changes.
I will add your email and Malathi's email to the access list on my account and we may find coordination more dynamic, as you say.
As it stands right now, I'm waiting for Malathi to forward me the changes to the files that he edited (about half). Once I receive those, I was planning on creating a new PDF and performing the other changes that you have requested. Malathi was in charge of the files concerning user-defined-token-classes so I was waiting to receive his modified files first, in order avoid redundant and conflicting changes.
Best,
Martin
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Are there any plans to apply a CSS in order to implement a nicer web documentation? Shouldn't we use, maybe a CMS such as drupal and then frame the documentation with its CSS?
Regards
Frank
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
The first revision of has been converted HTML and I have placed it in the dropbox folder as main.html. My earlier problem with asciidoc had been that I didn't have source-highlight installed.
The PDF should be ready shortly.
I have not yet received Malathi's edits, so only a little more than half of the files have been edited.
There is still much to do, as the above posts detail. I will look into reformatting with CSS after further content revisions are made.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
The pdf has been added to Dropbox. The filename is main.pdf.
It certainly needs more work. asciidoc was able to render the "X" into the html file, but somewhere along the line the PDF file handles it incorrectly.
The flow has been .txt -> asciidoc -> .docbook -> xsltproc -> .fo -> fop -> .pdf
My guess is that fop is the problem, and I will try other PDF generation software (dblatex).
Now that I've generated these primitive versions of the files, I'm getting a better sense of how formatting could be changed.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
... and Martin, please, add your and Malathis name to the list of authors of the document. Simply, find a way to distinguish the developer of the software from those who should take credit for the work on the documentation.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
you are now a developper with the 'technician' role. You still do not have write access to the SVN system. But, you should be able to make new releases. Please, only release documentation. There's good documentation on SF of how to do that.
Basically, you need to transfer the data to frs.sourceforge.net/uploads
and then follow the instructions on Admin/File Releases. Again, please,
only Add Releases to 'Documentation' not to any other package.
Best Regards.
Frank
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
I uploaded an HTML file to the documentation section. There are just a couple minor changes, I was more or less trying to figure out the upload system.
Note that the images don't show up, because I didn't re-upload them, since I wasn't sure if you intended to keep the doc there, or use it to replace the current HTML on the website. In hindsight, it may be worth it to wait until I have the next major revision ready.
In other news, I should have the pdf ready shortly, I'm pretty sure the trouble has been the font that FOP uses by default.
Martin
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
please, overwrite the old with the newest version. Do always do so. I'm currently on vacation in my homeland-region and the internet connection is not that fast. There are some changes, which I did to the 'skipper' section, since this feature is new in quex 0.32.1.
I'll try to send it into your drop-box.
Did you try the xhtml output of asciidoc. this would allow a 'pagewise' design of the documentation.
Regards
Fran
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
I'm not entirely sure what you mean by pagewise. I regenerated the file with the table of contents and numbering attributes, which definitely improves the usability. Is that what you were talking about?
Regards,
Martin
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
OK, I was talking about the HTML documentation. What I meant was that the documentation is currently one single page. At the time when I was playing around with AsciiDoc I somehow managed to get an index page and each chapter or section as a different html source file. I remember it fuzzily to have something to do with xhtml output.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
I just discovered this thread. It's 3 years since a last post. Is
documentation still being worked on? Are the weekly Friday Skype sessions
still going on?
The documentation, of course, is still worked on. It is only
me who is working on it, now-and I am currently focussing
on development.
The Friday weekly meetings are no longer. If there is something
serious to discuss, we could very well setup a meeting. To be
honest, I am glad to get Quex progress without being able
to give too much attention on user inputs. Hopefully, this is
going to change in a month or so.
Best Regards
Frank
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
Hello to all interested in improving the Quex documentation,
We're happy to have you. I have started this thread to coordinate our efforts to improve the Quex docs. The doc improvement project has just begun, so there is still a lot to do.
Currently, we are going over the current text and making minor edits (fixing spelling and grammar problems for instance). Below is a list of the txt files found in the quex docs.
I have placed an 'X' next to the files that have been lightly edited by me.
To those interested in joining, I ask you to read through the txt files to get a feel for what Quex can do. I would also ask that you post here which files you would like to edit.
Once these files have been edited, we will discuss the bigger changes that need to be made (format, style, order).
Without further delay, here's the list:
Xquex/appendix/example-indentation.txt
Xquex/appendix/ucs_properties/intro.txt
Xquex/appendix/ucs_properties/property-settings.txt
Xquex/basics/indentation.txt
Xquex/basics/intro.txt
Xquex/basics/line-column-counting.txt
Xquex/basics/mode-inheritance.txt
quex/basics/mode-transitions.txt -------------------------------------some
Xquex/basics/modes.txt
Xquex/basics/pattern-matching.txt
Xquex/basics/start-mode.txt
Xquex/basics/summary.txt
quex/basics/token-queue.txt
Xquex/DEBUG_switches.txt
Xquex/formal/character-encoding/intro.txt
Xquex/formal/code-sections.txt
Xquex/formal/command-line-options.txt
Xquex/formal/derivation.txt
Xquex/formal/generated-class/accumulator.txt
Xquex/formal/generated-class/class-body-extension.txt
quex/formal/generated-class/constructor-extension.txt
quex/formal/generated-class/intro.txt
quex/formal/generated-class/mode-handling.txt
quex/formal/generated-class/mode-objects.txt
quex/formal/generated-class/switching-buffers.txt
quex/formal/generated-class/token-handling.txt
quex/formal/generated-class/ui.txt
quex/formal/generated-class/virtual-functions.txt
quex/formal/indentation-events.txt
quex/formal/intro.txt
quex/formal/macro.txt
quex/formal/match_event.txt
quex/formal/mode-transitions-caveat.txt
quex/formal/mode-transitions.txt
quex/formal/modes.txt
quex/formal/pasting-header.txt
quex/formal/pattern-action-priorities.txt
quex/formal/pattern-action-shortcuts.txt
quex/formal/pattern-action.txt
quex/formal/pattern-names.txt
quex/formal/patterns/character-set-expressions.txt
quex/formal/patterns/context-dependent-pitfalls.txt
quex/formal/patterns/context-dependent.txt
quex/formal/patterns/context-free-pitfalls.txt
quex/formal/patterns/context-free.txt
quex/formal/patterns/intro.txt
quex/formal/patterns/test.txt
quex/formal/patterns/ucs-properties.txt
quex/formal/user-token-class.txt
quex/header.txt
quex/inside-quex/buffer/API.txt
quex/inside-quex/buffer/constructor.txt
quex/inside-quex/buffer/input-methods.txt
quex/inside-quex/buffer/intro.txt
quex/inside-quex/buffer/load.txt
quex/inside-quex/buffer/mechanisms.txt
quex/inside-quex/buffer/test.txt
quex/inside-quex/code-generation/core.txt
quex/inside-quex/code-generation/header.txt
quex/inside-quex/code-generation/state-transitions.txt
quex/inside-quex/hopcroft-optimization.txt
quex/inside-quex/intro/generation-steps.txt
quex/inside-quex/intro/intro.txt
quex/inside-quex/intro/post-conditions.txt
quex/inside-quex/intro/pre-conditions.txt
quex/inside-quex/intro/the-big-picture.txt
quex/inside-quex/intro.txt
quex/inside-quex/labeling-states.txt
quex/inside-quex/NFA-to-DFA.txt
quex/inside-quex/OLD-state-transition.txt
quex/inside-quex/test.txt
quex/inside-quex/thomson-construction/intro.txt
quex/inside-quex/thomson-construction/parallel.txt
quex/inside-quex/thomson-construction/repetition.txt
quex/inside-quex/thomson-construction/serial.txt
quex/intro/authors-remark.txt
quex/intro/features.txt
quex/intro/installation.txt
quex/intro/intro.txt
quex/intro/license.txt
quex/intro/naming.txt
quex/intro/philosophie.txt
quex/intro/remark.txt
quex/main-outsourced.txt
quex/main.txt
quex/performance-hints.txt
quex/plot/intro.txt
quex/practical/calling-quex.txt
quex/practical/dumpster.txt
quex/practical/example.txt
quex/practical/intro.txt
quex/practical/modes.txt
quex/practical/pattern-action-pairs.txt
quex/practical/patterns.txt
quex/practical/skipper.txt
quex/practical/summary.txt
quex/practical/token-ids.txt
quex/query/character-set-expressions.txt
Xquex/query/intro.txt
quex/query/properties.txt
quex/query/property-wilcard-expansions.txt
Xquex/quick-start.txt
Just let us know what you plan to edit, and assign yourself a letter.
I'm open to any ideas or suggestions you have.
Regards
Martin Miller
Hi Martin,
As you suggested, I will take up reviewing of files
from "quex/formal/generated-class/constructor-extension.txt" to
"quex/inside-quex/hopcroft-optimization.txt". Henceforth, I will be using letter 'M' before all the files that I review.
As I am a newbie to 'Open Source', I request you to guide me through the process and inform me about the intricacies involved.
Regards,
Malathi Voodi
Buffer Handling API:
please, do not consider any current state of the buffer handling API as it is currently documented. There has been major changes which are not included in the documentation. The question is: Can anyone figure out the design from the code,
or shall I better write a draft.
Would anyone be interested in setting up a Doxygene Environment for the
documentation of the 'code_base/' directory's code?
Regards
Frank
Doxygen looks interesting and I'd like to figure it out, but I've gotten a little behind on the txt edits.
Malathi, if you'd like to extract the buffer handling documentation using Doxygen, go ahead.
Otherwise, if I finish up in the next couple of days and nobody else has volunteered to do it, I'll see if I can figure it out, since it doesn't seem too complicated (at least the concept, implementation is probably a different story).
I just got an ethernet connection (as opposed to wireless) again, since I just moved, and I fear that configuring my FreeBSD mediaserver has distracted me.
Martin
After some delay, I have finished the preliminary edits of the txt files. Malathi finished his some time ago, and once I have received his edited files I will create the new PDF, which can be used until the next revision of the documentation is ready.
Still to do:
"The token ids are by default placed in the global namespace and the
default token prefix is "QUEX_TKN_".
This happens as a conclusion to the issue described in bug report
2136054.
The new behavior may also have import on the documentation for 'user
defined token classes'."
For the major edits, I suggest that Malathi edit the files that I edited in the first round, and vice-versa. Anybody wishing to join (and I encourage you to) can volunteer and a portion of the editing will be given to him.
Any issues that come up while doing these major edits can be posted here for discussion.
Thanks Martin.
Next point: Command line option "--output-directory" and "--odir" allow to define an output directory since 0.32.1 (release to come out soon).
We must somehow find a way to coordinate the work more dynamically. Maybe, you want to have write access to the svn repository?
Regards
Frank
I just read the access restriction documentation and it says that there is no per-path access restriction possible. Thus, we might be better off with a 'ping-pong' procedure, where you send me the docuementation as soon as you have something not necessarily perfect. I can then do my changes, add a note, and send it back. What do you think?
Frank,
I was wondering about svn access myself. An alternative would to use another web-storage option for modifying the documentation amongst ourselves. Are you familiar with Dropbox (http://www.getdropbox.com/)? It's a web-storage/collaboration app that will allow us to synch our versions of the documentation in, essentially, real time. I created a symbolic link to my quex directory in the Dropbox folder that was created. Once you receive my email granting access you should be able to easily view and comment on my changes.
I will add your email and Malathi's email to the access list on my account and we may find coordination more dynamic, as you say.
As it stands right now, I'm waiting for Malathi to forward me the changes to the files that he edited (about half). Once I receive those, I was planning on creating a new PDF and performing the other changes that you have requested. Malathi was in charge of the files concerning user-defined-token-classes so I was waiting to receive his modified files first, in order avoid redundant and conflicting changes.
Best,
Martin
Are there any plans to apply a CSS in order to implement a nicer web documentation? Shouldn't we use, maybe a CMS such as drupal and then frame the documentation with its CSS?
Regards
Frank
The first revision of has been converted HTML and I have placed it in the dropbox folder as main.html. My earlier problem with asciidoc had been that I didn't have source-highlight installed.
The PDF should be ready shortly.
I have not yet received Malathi's edits, so only a little more than half of the files have been edited.
There is still much to do, as the above posts detail. I will look into reformatting with CSS after further content revisions are made.
Great Job.
Martin, would you like to become a developper? This way you could release the documentation by your self.
Best Regards
Frank
The pdf has been added to Dropbox. The filename is main.pdf.
It certainly needs more work. asciidoc was able to render the "X" into the html file, but somewhere along the line the PDF file handles it incorrectly.
The flow has been .txt -> asciidoc -> .docbook -> xsltproc -> .fo -> fop -> .pdf
My guess is that fop is the problem, and I will try other PDF generation software (dblatex).
Now that I've generated these primitive versions of the files, I'm getting a better sense of how formatting could be changed.
... and Martin, please, add your and Malathis name to the list of authors of the document. Simply, find a way to distinguish the developer of the software from those who should take credit for the work on the documentation.
Suggestion:
.txt --(asciidoc)--> .tex --(pdflatex)--> *.pdf
I only have the best experiences with TeX. But the question about the source-higlighting remains.
Also, I saw that the 'chi' in Quex in the document has become a '#'. Maybe we should change that.
Anyway, it looks like a great job.
Thanks.
Of course you can put me on as a developer. Let me know if there's anything I need to know to release the docs.
I haven't had any luck yet getting the chi to render correctly, but I'll keep trying.
Martin,
you are now a developper with the 'technician' role. You still do not have write access to the SVN system. But, you should be able to make new releases. Please, only release documentation. There's good documentation on SF of how to do that.
Basically, you need to transfer the data to frs.sourceforge.net/uploads
and then follow the instructions on Admin/File Releases. Again, please,
only Add Releases to 'Documentation' not to any other package.
Best Regards.
Frank
Frank,
I uploaded an HTML file to the documentation section. There are just a couple minor changes, I was more or less trying to figure out the upload system.
Note that the images don't show up, because I didn't re-upload them, since I wasn't sure if you intended to keep the doc there, or use it to replace the current HTML on the website. In hindsight, it may be worth it to wait until I have the next major revision ready.
In other news, I should have the pdf ready shortly, I'm pretty sure the trouble has been the font that FOP uses by default.
Martin
Martin,
please, overwrite the old with the newest version. Do always do so. I'm currently on vacation in my homeland-region and the internet connection is not that fast. There are some changes, which I did to the 'skipper' section, since this feature is new in quex 0.32.1.
I'll try to send it into your drop-box.
Did you try the xhtml output of asciidoc. this would allow a 'pagewise' design of the documentation.
Regards
Fran
There are now only 7 instances where the # shows up instead of a chi in the PDF, unfortunately that includes the title page.
Frank,
I'm not entirely sure what you mean by pagewise. I regenerated the file with the table of contents and numbering attributes, which definitely improves the usability. Is that what you were talking about?
Regards,
Martin
OK, I was talking about the HTML documentation. What I meant was that the documentation is currently one single page. At the time when I was playing around with AsciiDoc I somehow managed to get an index page and each chapter or section as a different html source file. I remember it fuzzily to have something to do with xhtml output.
To all:
Frank will be hosting a discussion of Quex issues on skype each Friday from 5:30-6:00am Berlin time. The user id is quex-cafe.
I just discovered this thread. It's 3 years since a last post. Is
documentation still being worked on? Are the weekly Friday Skype sessions
still going on?
I started this thread on the typos I've found in the 0.50.1 PDF documentation:
https://sourceforge.net/tracker/?func=detail&aid=3432095&group_id=168259&atid
=846112
The documentation, of course, is still worked on. It is only
me who is working on it, now-and I am currently focussing
on development.
The Friday weekly meetings are no longer. If there is something
serious to discuss, we could very well setup a meeting. To be
honest, I am glad to get Quex progress without being able
to give too much attention on user inputs. Hopefully, this is
going to change in a month or so.
Best Regards
Frank
I'd be happy to incorporate my fixes to relieve you of that burden, if you
want.
In any case, I'm quite excited to be using Quex. It's working the way that I
had hoped, so it's been useful to me.
Thanks so much!