Ref. Man. Softs: Are comments into Bibtex (bib) documents possible?

Xeratul · 04-10-2017, 10:10 AM

Hello,

Regarding reference manager softwares on linux (i.e. bib), are comments into Bibtex (bib) eventually documents possible and reliable to do?

Code:

/* this is ma comment one */
# this is comment 2
# this comment works too on jabref and bib software managers. 
@article{key829734,
title = "linux title of article",
author = "super tux",
}

# bla bla, this comment works too on jabref and bib software managers.

Thank you in advance for your inputs!

rtmistler · 04-11-2017, 07:22 AM

Regarding your initial question, it is reliable to do this within code, the finding and generation of documentation from the comments in code works flawlessly from a technical point of view. I've done it and used it.

The results, I have a very different opinion about.

I apologize for sounding defeatist about this, however over the years I've literally seen dozens of packages for exactly this.

Unless the entire team sells into the concept, it does not work. Usually one person persists in trying to make this, or similar happen, for some period of time until they get too busy to be able to maintain.

The other problem is that while management may be temporarily convinced to mandate that everyone format their file headers a certain way, (1) things will slip though the cracks, (2) those who don't care will put the minimal info into these headers making them ineffective to a degree, (3) over time the information becomes out of date, (4) I've seen "documentation" generated by this tactic and it is not worthwhile - at this point management stops bothering people about formatting their headers in some special way. The real truth is that while the concept was temporarily "sold" that the code can generate it's own documentation, the head proponent of it has their one ideal example which they use to sell the concept. They, their self do not always follow-up when they are with the larger team participating, and instead revert to copying the minimal header with no information. And the other part is that management never really bought into it anyways. For the product documentation, they have a technical writer and that person never stopped doing their job. For interface specifications, they have the design documents and they tell the engineers to write Word or PDF documents to describe the interfaces for external users of the software or library. Plus you cannot easily draw a block diagram in code, or describe the functions of a state machine in code.

What does work instead are:

Clear organization of sub-systems
Consistent file and function naming conventions
Consistent coding styles and manners of declaring all variables, macros, functions, structures, type defines, and doing so the same way for all sub-systems of code
Providing example or test code which results in valid, provable outcomes
Documentation of the code - if it is auto-generated as you're discussing here then it has to be consistent across every file so that it appears consistent and comprehensive to the reader, however auto-generation of a bunch of functions is not the entire picture. Documentation needs to also describe the flow of the architecture, the life of a packet of data, the life of biometric data from subject to graph, or other similar paradigms.

Xeratul · 04-11-2017, 03:43 PM

Quote:

Originally Posted by rtmistler

Regarding your initial question, it is reliable to do this within code, the finding and generation of documentation from the comments in code works flawlessly from a technical point of view. I've done it and used it.

The results, I have a very different opinion about.

I apologize for sounding defeatist about this, however over the years I've literally seen dozens of packages for exactly this.

Unless the entire team sells into the concept, it does not work. Usually one person persists in trying to make this, or similar happen, for some period of time until they get too busy to be able to maintain.

The other problem is that while management may be temporarily convinced to mandate that everyone format their file headers a certain way, (1) things will slip though the cracks, (2) those who don't care will put the minimal info into these headers making them ineffective to a degree, (3) over time the information becomes out of date, (4) I've seen "documentation" generated by this tactic and it is not worthwhile - at this point management stops bothering people about formatting their headers in some special way. The real truth is that while the concept was temporarily "sold" that the code can generate it's own documentation, the head proponent of it has their one ideal example which they use to sell the concept. They, their self do not always follow-up when they are with the larger team participating, and instead revert to copying the minimal header with no information. And the other part is that management never really bought into it anyways. For the product documentation, they have a technical writer and that person never stopped doing their job. For interface specifications, they have the design documents and they tell the engineers to write Word or PDF documents to describe the interfaces for external users of the software or library. Plus you cannot easily draw a block diagram in code, or describe the functions of a state machine in code.

What does work instead are:

Clear organization of sub-systems
Consistent file and function naming conventions
Consistent coding styles and manners of declaring all variables, macros, functions, structures, type defines, and doing so the same way for all sub-systems of code
Providing example or test code which results in valid, provable outcomes
Documentation of the code - if it is auto-generated as you're discussing here then it has to be consistent across every file so that it appears consistent and comprehensive to the reader, however auto-generation of a bunch of functions is not the entire picture. Documentation needs to also describe the flow of the architecture, the life of a packet of data, the life of biometric data from subject to graph, or other similar paradigms.

what about hacking the system, to make a sort of format that will be adaptable in the future.
I thought about such a system, herewith, that fixed all those issues. It works for latex, but it may be extended to bib, to do something serious in it. I like "//" or "/* */" to comment out.
http://www.linuxquestions.org/questi...mb-4175600629/