Re: handling description markup/semantics for SQLite3 "output"?
Travis Everett <[email protected]> Mon, 10 Jul 2017 10:54:54 -0500
| Newsgroups | gmane.text.doxygen.devel |
|---|---|
| Message-ID | <CAC=jSUX+14uGzxQyvQnVPknvFZQSBuNtc=d4mUfsNY5R2QMChA@mail.gmail.com> |
--===============7473906974260443870== Content-Type: multipart/alternative; boundary="94eb2c05c35ea558ec0553f89ac4" --94eb2c05c35ea558ec0553f89ac4 Content-Type: text/plain; charset="UTF-8" Hi again Adrian, I agree with what you've said, but I think that only holds when the detaileddescription database field holds a *single* format. An example of the input/output I'm working with might be more useful than my initial description: https://gist.github.com/abathur/ b3d3d25885303eb216e0ffa2d2604034 In this example, you can see that the string going into the database contains three different formats: an HTML header, plaintext markup, and Doxygen commands. Context: `generateSqlite3ForPage` is one of the parts of sqlite3gen that I'm refining as I work on a broader project that generates Doxygen-ready source files and markdown pages from a large Sphinx/RST corpus. Cheers, Travis On Sun, Jul 9, 2017 at 11:48 PM, Adrian M Negreanu <[email protected]> wrote: > Hi Travis, > > The format of the description is dictated by the client's needs. Or in > other words, where that description is used. > > I'm using it from python scripts which makes it easy to parse the current > plain text. > > This brings me to the question : why do you need another format, say (A), > when you'll already have to parse the plaintext format to extract the > semantic needed by (A) ? > > One reason for adding (A) is "it's easier for the client to use/parse", > which brings me again, to the first part : what client do you have ? > > Regards > > > On Jul 10, 2017 3:21 AM, "Travis Everett" <[email protected]> > wrote: > > All, > > I'm resuming work on refining the experimental SQLite3 output. I've run > into a pretty obvious quandary that I was blissfully ignorant of: > > Before output-format-specific conversion, it looks like detailed > descriptions can include (at least) a mix of HTML and raw text that still > contains doxygen commands (I haven't gone fishing, but my guess is that > markdown gets translated down to HTML, and output translators are > responsible for the rest). > > When it's being served by an SQL database, it doesn't seem like there's an > "obvious" or "expected" format for presentational/semantic markup embedded > in the detailed description. I was a bit surprised to find plaintext > Doxygen commands present at this stage. > > I'm curious if anyone has thoughts on how to handle these. The best three > paths forward seem to be: > > - Saving it as XML. I'm not keen on this since it significantly raises the > bar on using the sql output, and would require either updating all of the > descriptions in place, or parsing them into a more useful form on each use. > - Saving an opinionated plaintext translation. This would retain simple > usability and avoid the update-all-descriptions or constantly-reparse > issues, as long as consumers can live with the format ;) > - Some active, user-configurable translation method (probably translate to > XML and then call a user-defined translator script as with input filters. > *not sure how complex this would be or where to start; may be getting out > of my depth. > > Thanks for any direction, > Travis > > ------------------------------------------------------------ > ------------------ > Check out the vibrant tech community on one of the world's most > engaging tech sites, Slashdot.org! http://sdm.link/slashdot > _______________________________________________ > Doxygen-develop mailing list > [email protected] > https://lists.sourceforge.net/lists/listinfo/doxygen-develop > > > --94eb2c05c35ea558ec0553f89ac4 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable <div dir=3D"ltr"><span style=3D"font-size:12.800000190734863px">Hi again Ad= rian,=C2=A0</span><div style=3D"font-size:12.800000190734863px"><br></div><= div style=3D"font-size:12.800000190734863px">I agree with what you've s= aid, but I think that only holds when the detaileddescription database fiel= d holds a=C2=A0<i>single</i>=C2=A0format.</div><div style=3D"font-size:12.8= 00000190734863px"><br></div><div style=3D"font-size:12.800000190734863px">A= n example of the input/output I'm working with might be more useful tha= n my initial description:=C2=A0<a href=3D"https://gist.github.com/abathur/b= 3d3d25885303eb216e0ffa2d2604034" target=3D"_blank">https://gist.github.com/= <wbr>abathur/<wbr>b3d3d25885303eb216e0ffa2d26040<wbr>34</a></div><div style= =3D"font-size:12.800000190734863px"><br></div><div style=3D"font-size:12.80= 0000190734863px">In this example, you can see that the string going into th= e database contains three different formats: an HTML header, plaintext mark= up, and Doxygen commands.=C2=A0</div><div style=3D"font-size:12.80000019073= 4863px"><br></div><div style=3D"font-size:12.800000190734863px">Context: `g= enerateSqlite3ForPage` is one of the parts of sqlite3gen that I'm refin= ing as I work on a broader project that generates Doxygen-ready source file= s and markdown pages from a large Sphinx/RST corpus.=C2=A0</div><div style= =3D"font-size:12.800000190734863px"><br></div><div style=3D"font-size:12.80= 0000190734863px">Cheers,</div><div style=3D"font-size:12.800000190734863px"= >Travis</div></div><div class=3D"gmail_extra"><br><div class=3D"gmail_quote= ">On Sun, Jul 9, 2017 at 11:48 PM, Adrian M Negreanu <span dir=3D"ltr"><= <a href=3D"mailto:[email protected]" target=3D"_blank">[email protected]</a>&= gt;</span> wrote:<br><blockquote class=3D"gmail_quote" style=3D"margin:0 0 = 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir=3D"auto"><div>= Hi Travis,</div><div dir=3D"auto"><br></div><div dir=3D"auto">The format of= the description is dictated by the client's needs. Or in other words, = where that description is used.</div><div dir=3D"auto"><br></div><div dir= =3D"auto">I'm using it from python scripts which makes it easy to parse= the current plain text.</div><div dir=3D"auto"><br></div><div dir=3D"auto"= >This brings me to the question : why do you need another format, say (A), = when you'll already have to parse the plaintext format to extract the s= emantic needed by (A) ?</div><div dir=3D"auto"><br></div><div dir=3D"auto">= One reason for adding (A) is "it's easier for the client to use/pa= rse", which brings me again, to the first part : what client do you ha= ve ?</div><div dir=3D"auto"><br></div><div dir=3D"auto">Regards</div><div d= ir=3D"auto"><br><div class=3D"gmail_extra" dir=3D"auto"><br><div class=3D"g= mail_quote"><div><div class=3D"h5">On Jul 10, 2017 3:21 AM, "Travis Ev= erett" <<a href=3D"mailto:[email protected]" target=3D"_bl= ank">[email protected]</a>> wrote:<br type=3D"attribution"></di= v></div><blockquote class=3D"m_5160916996955980396quote" style=3D"margin:0 = 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div><div class=3D"h5= "><div dir=3D"ltr">All,<div><br></div><div>I'm resuming work on refinin= g the experimental SQLite3 output. I've run into a pretty obvious quand= ary that I was blissfully ignorant of:</div><div><br></div><div>Before outp= ut-format-specific conversion, it looks like detailed descriptions can incl= ude (at least) a mix of HTML and raw text that still contains doxygen comma= nds (I haven't gone fishing, but my guess is that markdown gets transla= ted down to HTML, and output translators are responsible for the rest).</di= v><div><br></div><div>When it's being served by an SQL database, it doe= sn't seem like there's an "obvious" or "expected&quo= t; format for presentational/semantic markup embedded in the detailed descr= iption. I was a bit surprised to find plaintext Doxygen commands present at= this stage.=C2=A0</div><div><br></div><div>I'm curious if anyone has t= houghts on how to handle these. The best three paths forward seem to be:</d= iv><div><br></div><div>- Saving it as XML. I'm not keen on this since i= t significantly raises the bar on using the sql output, and would require e= ither updating all of the descriptions in place, or parsing them into a mor= e useful form on each use.</div><div>- Saving an opinionated plaintext tran= slation. This would retain simple usability and avoid the update-all-descri= ptions or constantly-reparse issues, as long as consumers can live with the= format ;)</div><div>- Some active, user-configurable translation method (p= robably translate to XML and then call a user-defined translator script as = with input filters. *not sure how complex this would be or where to start; = may be getting out of my depth.</div><div><br></div><div>Thanks for any dir= ection,</div><div>Travis</div></div> <br></div></div>------------------------------<wbr>------------------------= ------<wbr>------------------<br> Check out the vibrant tech community on one of the world's most<br> engaging tech sites, Slashdot.org! <a href=3D"http://sdm.link/slashdot" rel= =3D"noreferrer" target=3D"_blank">http://sdm.link/slashdot</a><br>_________= _____________________<wbr>_________________<br> Doxygen-develop mailing list<br> <a href=3D"mailto:[email protected]" target=3D"_blank">= [email protected]<wbr>rge.net</a><br> <a href=3D"https://lists.sourceforge.net/lists/listinfo/doxygen-develop" re= l=3D"noreferrer" target=3D"_blank">https://lists.sourceforge.net/<wbr>lists= /listinfo/doxygen-develop</a><br> <br></blockquote></div><br></div></div></div> </blockquote></div><br></div> --94eb2c05c35ea558ec0553f89ac4-- --===============7473906974260443870== Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: inline ------------------------------------------------------------------------------ Check out the vibrant tech community on one of the world's most engaging tech sites, Slashdot.org! http://sdm.link/slashdot --===============7473906974260443870== Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: inline _______________________________________________ Doxygen-develop mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/doxygen-develop --===============7473906974260443870==--