LinuxQuestions.org
Latest LQ Deal: Latest LQ Deals
Go Back   LinuxQuestions.org > Forums > Linux Forums > Linux - Software
User Name
Password
Linux - Software This forum is for Software issues.
Having a problem installing a new program? Want to know which application is best for the job? Post your question in this forum.

Notices


Reply
  Search this Thread
Old 04-10-2017, 11:10 AM   #1
Xeratul
Senior Member
 
Registered: Jun 2006
Location: UNIX
Distribution: FreeBSD
Posts: 2,357

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


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!
 
Old 04-11-2017, 08:22 AM   #2
rtmistler
Moderator
 
Registered: Mar 2011
Location: USA
Distribution: MINT Debian, Angstrom, SUSE, Ubuntu, Debian
Posts: 8,438
Blog Entries: 13

Rep: Reputation: 3747Reputation: 3747Reputation: 3747Reputation: 3747Reputation: 3747Reputation: 3747Reputation: 3747Reputation: 3747Reputation: 3747Reputation: 3747Reputation: 3747
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:
  1. Clear organization of sub-systems
  2. Consistent file and function naming conventions
  3. 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
  4. Providing example or test code which results in valid, provable outcomes
  5. 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.

Last edited by rtmistler; 04-11-2017 at 08:24 AM.
 
Old 04-11-2017, 04:43 PM   #3
Xeratul
Senior Member
 
Registered: Jun 2006
Location: UNIX
Distribution: FreeBSD
Posts: 2,357

Original Poster
Rep: Reputation: 213Reputation: 213Reputation: 213
Quote:
Originally Posted by rtmistler View Post
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:
  1. Clear organization of sub-systems
  2. Consistent file and function naming conventions
  3. 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
  4. Providing example or test code which results in valid, provable outcomes
  5. 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/
 
  


Reply


Thread Tools Search this Thread
Search this Thread:

Advanced Search

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is Off
HTML code is Off



Similar Threads
Thread Thread Starter Forum Replies Last Post
Efficient reference manager software for bib files on Linux? Xeratul Linux - Software 1 04-05-2017 02:19 AM
Poor Man's intrusion detection/notification - Request for Comments: smithware Linux - Security 3 08-13-2013 04:26 PM
[SOLVED] What's the bib deal of uuid with postgres/jdbc? eantoranz Programming 3 03-20-2012 01:58 PM
where the softs goes pento_pento Linux - Newbie 4 09-01-2009 09:24 AM
man documents, how is it viewed. pranavojha Linux - Newbie 5 03-26-2006 10:31 AM

LinuxQuestions.org > Forums > Linux Forums > Linux - Software

All times are GMT -5. The time now is 01:43 AM.

Main Menu
Advertisement
My LQ
Write for LQ
LinuxQuestions.org is looking for people interested in writing Editorials, Articles, Reviews, and more. If you'd like to contribute content, let us know.
Main Menu
Syndicate
RSS1  Latest Threads
RSS1  LQ News
Twitter: @linuxquestions
Facebook: linuxquestions Google+: linuxquestions
Open Source Consulting | Domain Registration