Possible documentation project of CCLDoc

[KZiemian]

A bit of context. Working on Common Lisp UltraSepc (CLUS) we decide to use CCLDoc to write it and create output. To do that we need to read CCLDoc code and puts some add-on. In that work we can produced some documentation and comments in the source as side effect, we need it ourselves to create add-ons.

Do you interested with such project of producing such documentation and if so, what standard of it we should adopted?

Additional information. CLUS is now multithreads project and CCLDoc related part is now all in my hands.

[xrme]

Thank you. I would be happy to review and consider merging any improvements to CCLDoc.

Those can be improvements to the documentation for CCLDoc (that is, to the file ccldoc.ccldoc), or to the code itself.

In general, I am not picky about coding standards.

Please avoid whitespace-only changes, especially when such changes are grouped with other changes. Just follow the existing style (and the usual Common Lisp conventions) and that will be fine.

[KZiemian]

This is best description of CLUS collaboration plans about CCLDoc add-ons that I can write. By no mean they is canonical list, I just collected and organized things about I talk and heard from wiser than me in CLUS matters folks. Also I don't know how realistic some points are or how much work to do it will be needed trying to realized it. I still try to fully understand my thread of work.

If someone need more information try contact community of CLUS on freenode #lisp, or Discord #clus-general. You can also read paper staying CLUS reason to be and aims. Unfortunately this paper is much outdated https://github.com/phoe/clus-data/blob/master/paper.pdf.

IMPORTANT
Statement of CLUS community now is: Content is a king! So now we are interested with creating web pages that have good CL content, giving it good look is not issue now. Because I have little idea how make web page look good, I decide do disregard this issue totally.

What we need to do with CCLDoc.

1. Create new tags for things like variable references, glossary entries, code blocks, diffrent kinds of result values, etc.
   EXAMPLE
   We want write something like
   "Function {:cl:functions:some-function}"
   which will expand to proper hyperlink to page with some-function.
2. We want create functions
   (load-graph *SOMETHING*)
(output-graph *SOMETHING* "somewhere")
   which creates not single HTML, but bunch of HTML pages hyper-linked with each others. This is connected with previous point, we want that all new defined tags expand in proper hyperlinks in this step.
3. To make former works, we need to define new class, call it GRAPH-DOCUMENT for now, that is related to class DOCUMENT in some not precised now way.

What we are doing now. There are two threads.

1. Create some proof of concept CCLDoc file (probably "Function GENSYM") that will used desired tags, which after we need to create.
2. a) Dig up into CCLDoc code enough to make creation of all add-ons possible.
   b) Create documentation of code that we understand as side effect of point a).

Unfortunately I now only person that works on second thread. Time will show what I can do in current situation.

If English of this post is bad, give me a sign, I try to correct it.

[KZiemian]

On "CCLDoc Overview" is note in description of :definition.

"Someday I'd like the signature to be a lisp expression that will be automatically converted to text with consistent markup for parameters and values, but that is not implemented right now. For now it might be best for document consistency to simply avoid markup in the signature."

If we can, should we add this code to CCLDoc?

Similar question to all other notes in Overview and source code.

[xrme]

Sure.

As you write documentation using CCLDoc notation, I am sure that you will have ideas for enhancements, and we can work together to add those.

[KZiemian]

I apologized if I do something wrong with pull request. I have a very little experience with cooperation on GitHub.

I also have two problems, I think it is not the worst place to post it.

1. CCLDoc Overview say that are three possible outputs now:
   "OUTPUT-DOCBOOK generates ​docbook output, OUTPUT-TRACWIKI generates ​Trac Wiki output, and OUTPUT-CCLDOC generates CCLDoc source output."
   OUTPUT-HTML is missing from this description. How to correct this omission?
2. Overview say that
   "A CCLDoc document is a tree of CLAUSE objects, rooted with a DOCUMENT object."
   But DOCUMENT inherits from SECTION
   

   ccldoc/source/representation.lisp

   Line 303 in ae902d6

   (defclass document (section)

   
   This mean that DOCUMENT is rooted on CLAUSE-OBJECT. Can you explain what I miss?

[KZiemian]

Thank you, for help. I remember all time that you said to avoid whitespace-only changes, but was not sure what do with autoformating of this commit. I switch if off now on my computer.

Second, my settings removes all whitespaces at the end of the line, I need it when working on CLUS. Should I switch it off too?

I apologized for so many basic question. I only have experience of working with CLUS on GitHub, but it have different rules of work.

[xrme]

I would not like to get changes that only delete trailing whitespace.

If you are working in some area, and you clean up nearby trailing whitespace and indentation as a side-effect of your other work, then that's fine.

[KZiemian]

I switch this option of whitespace removing off, so this should not happen in future.

Now it looks like that I need to start with representation.lisp file. I will try to make some substantive comment to it in the next two weeks. I will try my best, but I most probably make many mistakes and errors on the way, like this time.