Literate: A Modern Literate Programming System
literate.zbyedidia.webfactional.com
Literate: A Modern Literate Programming System
1–10 of 20 posts
Re: Literate: A Modern Literate Programming System
#2I think a problem with literate programming is that programs are never written from top to bottom, at least not in conventional programming languages. The same holds for books, of course, but not in such a dramatic way. Therefore, I think the best way to read a program is not from top to bottom, but rather by using some kind of search tool.
By the way, does anybody know of an automated way to "grade" the quality of code documentation? I think this is what we need on repositories such as github, as it could stimulate the production of documentation of better quality (in most cases the documentation of OSS projects is rather poor).
Re: Literate: A Modern Literate Programming System
#3It looks like this software breaks compiler error messages.
One of the great features of Knuth and Levy's CWEB is that errors are reported in terms of locations in the literate source. This feature, which works by way of line pragmas, is essential for proper debugger support and, in my opinion, sanity while coding larger projects.
If it is missing, it is often better to skip the "tangle" step entirely and have the literate source map directly to the program source line for line. Trying to "pattern-match" the compiler errors against tags in the source file is a painful waste of time. The 1-1 mapping is quite practical for more functional languages if one writes code in a style more like SICP than the TeX sources.
Re: Literate: A Modern Literate Programming System
#4Quick editing fix, under the section "features of this tool". I think this; "The code that is generated is indented property" should read as 'indented properly'.
Re: Literate: A Modern Literate Programming System
#5It looks like this software breaks compiler error messages. One of the great features of Knuth and Levy's CWEB is that errors are reported in terms of locations in the literate source. This feature, which works by way of line pragmas, is essential for proper debugger support and, in my opinion, sanity while coding larger projects. If it is missing, it is often better to skip the "tangle" step entirely and have the li…
Thanks for the comment. Because this "Literate" software outputs nicely formatted code (including automatically included comments identifying code blocks) in the target language, it's not too big a deal, you can just see what line the compiler errors are referring to in the target source code. CWEB's approach of treating the tangled code as only intended for machine reading has the major drawback that you can't share the target source code with others and expect them to be able to read it; they need to buy into CWEB too. So there's a trade-off here.
Re: Literate: A Modern Literate Programming System
#6Quick editing fix, under the section "features of this tool". I think this; "The code that is generated is indented property" should read as 'indented properly'.
Thanks, it's fixed now.
Re: Literate: A Modern Literate Programming System
#7It looks like this software breaks compiler error messages. One of the great features of Knuth and Levy's CWEB is that errors are reported in terms of locations in the literate source. This feature, which works by way of line pragmas, is essential for proper debugger support and, in my opinion, sanity while coding larger projects. If it is missing, it is often better to skip the "tangle" step entirely and have the li…
Thanks for the comment. Because this "Literate" software outputs nicely formatted code (including automatically included comments identifying code blocks) in the target language, it's not too big a deal, you can just see what line the compiler errors are referring to in the target source code. CWEB's approach of treating the tangled code as only intended for machine reading has the major drawback that you can't share…
> CWEB's approach of treating the tangled code as only intended for machine reading has the major drawback that you can't share the target source code with others and expect them to be able to read it; they need to buy into CWEB too.
There's not much of a trade off there. Either you use the tools that generated the code and edit their inputs, or the first time you update the code and rebuild your changes get clobbered.
And if people really find that literate programming makes the code that much harder to follow that they'd rather not use it, maybe it's not a great idea to use it.
Re: Literate: A Modern Literate Programming System
#8I think a problem with literate programming is that programs are never written from top to bottom, at least not in conventional programming languages. The same holds for books, of course, but not in such a dramatic way. Therefore, I think the best way to read a program is not from top to bottom, but rather by using some kind of search tool. By the way, does anybody know of an automated way to "grade" the quality of c…
Yeah, it just seems to me that wonderfully written literate documentation would be poorly organized software, and wonderfully organized software would be poorly organized documentation.
I guess what I mean by that is that as software scales out, your code will be more along the lines of "do this logic whenever this function/method happens to be invoked". So it would be great for documenting the workings of a function/method, but it would be poor for actually documenting the lifecycle of a logic path, like the lifecycle of a request. I certainly wouldn't have one file where I handle a request, do some business logic, and interact with a database, even though that is how you might document a lifecycle the request.
Re: Literate: A Modern Literate Programming System
#9It looks like this software breaks compiler error messages. One of the great features of Knuth and Levy's CWEB is that errors are reported in terms of locations in the literate source. This feature, which works by way of line pragmas, is essential for proper debugger support and, in my opinion, sanity while coding larger projects. If it is missing, it is often better to skip the "tangle" step entirely and have the li…
Thanks for the comment. Because this "Literate" software outputs nicely formatted code (including automatically included comments identifying code blocks) in the target language, it's not too big a deal, you can just see what line the compiler errors are referring to in the target source code. CWEB's approach of treating the tangled code as only intended for machine reading has the major drawback that you can't share…
It seems like this could be solved by making it an option? During development, generate line number pragmas to improve the error messages. Then when you have a working program, format the code nicely.
Re: Literate: A Modern Literate Programming System
#10Earlier quoted context omitted.
Thanks for the comment. Because this "Literate" software outputs nicely formatted code (including automatically included comments identifying code blocks) in the target language, it's not too big a deal, you can just see what line the compiler errors are referring to in the target source code. CWEB's approach of treating the tangled code as only intended for machine reading has the major drawback that you can't share…
It seems like this could be solved by making it an option? During development, generate line number pragmas to improve the error messages. Then when you have a working program, format the code nicely.
That's an excellent idea. I don't think it would work for all languages, but it's still a good solution, and will be added to the TODO list.