راهنمای وارد کردن کد در متن

از پارسی لاتک
پرش به: ناوبری، جستجو

در این نوشتار قصد داریم تا در مورد نحوه وارد کردن کد در متن توسط بسته listings صحبت کنیم.

اهداف و مزایا

Dfkcode1.png

فرض کنید که شما یک برنامه به زبانی مانند C، JAVA، MATLAB و ... نوشته اید که می‌خواهید به هر علتی کد آن را در داخل متن وارد کنید. احتمالا قبل از آشنایی با بسته listings، شما کد خود را در متن از طریق روش بردار و بچسبان (copy and paste) وارد می‌کردید و زمان زیادی را صرف این می کردید که شکل و شمایل آن به مانند حالتی گردد که در محیط های برنامه نویسی مشاهده می کنید. اما توسط بسته listings‌ براحتی و به سادگی هر چه تمام تر می توانید فایل کد خود را در متن با همان فرمتی که شما در نرم افزار های برنامه نویسی مشاهده می‌کنید وارد کنید. در این نوشتار قصد داریم تا شما را با نحوه کارکرد این بسته آشنا سازیم. مثالی از این مبحث در پیوند Insert Code قرار دارد.

وارد کردن بسته listings

در شروع کار بسته listings را با دستور usepackage فراخوانی کنید. دقت کنید که این بسته را با بسته listing اشتباه نکنید. در این مرحله به نکات زیر دقت کنید.

  1. اگر در حال نوشتن یک متن فارسی با استفاده از بسته xepersian هستید، دقت کنید که بسته xepersian حتما حتما باید آخرین بسته ای باشد که فراخوانی می شود. این قانون کاملا کلی است و در هر متنی که شما قصد نوشتن آن را با استفاده از xepersian دارید باید رعایت شود.
  2. بسته hyperref جزو آخرین بسته هایی باید باشد که فراخوانی می شود. این قانون هم کلی است.
  3. بسته listings قبل از دو بسته یاد شده باید وارد شود.
  4. به صورت پیش فرض کدهای وارد شده توسط بسته listings به صورت سیاه و سفید وارد متن می شوند. اگر می‌خواهید کدهای شما در متن به صورت رنگی باشد، مثلا کامنت ها به رنگ سبز باشند، باید بسته color‌ و xcolor را وارد کنید. البته وارد کردن این دو بسته کافی نیست بلکه باید یکسری تنظیماتی که در قسمت های بعدی بیان خواهد شد را نیز انجام دهید.

پس خواهیم داشت.

\usepackage[usenames,dvipsnames]{color,xcolor}
\usepackage{listings}
\usepackage{hyperref}
\usepackage{xepersian}

وارد کردن کد در متن

فرض کنید که یک کد MATLAB در فایلی به نام myFun.m نوشته اید که می خواهید آن را در متن وارد کنید. با استفاده از بسته listings کد خود را به دو شیوه می‌توانید در متن وارد کنید.

  1. وارد کردن فایل کد
  2. وارد کردن کد به صورت خام

وارد کردن فایل کد

در هر جایی از متن که می خواهید، کد شما وارد گردد، از دستور lstinputlisting استفاده کنید. به عنوان مثال برای وارد کردن همان فایل myFun.m باید به صورت زیر عمل کنید.

\begin{latin}
\lstinputlisting[language=Matlab]{myFun.m}
\end{latin}

نکات:

  • Latex به دنبال فایل myFun.m در پوشه فعلی (پوشه ای که فایل tex در آن قرار دارد) می‌گردد. اگر فایل myFun.m در مسیر دیگری قرار دارد باید مسیر کامل را در آرگومان ورودی دستور lstinputlisting مشخص کنید. به عنوان مثال اگر فایل شما در شاخه‌ای به نام Code در پوشه فایل tex شما وجود دارد باید به صورت زیر عمل کنید.
\begin{latin}
\lstinputlisting[language=Matlab]{Code/myFun.m}
\end{latin}
  • تنظیمات بسته listings را می‌توانید در زمان فراخوانی lstinputlisting وارد کنید. برای مثال در این جا من فقط از تنظیم تعیین زبان (language) استفاده کردم، و آن را بر روی زبان Matlab قرار دادم. این option به listings‌ کمک می‌کند تا کد شما را در قالب زبان MATLAB وارد کند.
  • اگر می خواهید کد در داخل یک متن فارسی وارد کنید، حتما آن را درون محیط latin قرار دهید. یعنی آن را در بین \begin{latin} و \end{latin} قرار دهید.
  • در صورتی که می خواهید کد را در یک متن انگلیسی وارد کنید باید خطوط \begin{latin} و \end{latin} را حذف کنید.
  • دقت کنید که به همراه اسم فایل، پسوند فایل را نیز وارد کنید.

وارد کردن به صورت خام

در روش دوم، شما می‌توانید اصل کد را در متن وارد کنید. در این جا نیز به مانند حالت قبل خود بسته listings تمامی تنظیمات مربوط به استایل کد را انجام می‌دهد. به عنوان مثال خطوط زیر را در نظر بگیرید.

\begin{latin}
\begin{lstlisting}[language=C]
#include <stdio.h>
#define N 10
/* Block
 * comment */
 
int main()
{
    int i;
 
    // Line comment.
    puts("Hello world!");
 
    for (i = 0; i < N; i++)
    {
        puts("LaTeX is also great for programmers!");
    }
 
    return 0;
}
\end{lstlisting}
\end{latin}

اگر به خروجی فایل pdf نگاهی بیاندازید خواهید دید که کدی در قالب زبان C در متن وارد شده است.

وارد کردن کد در متن
  • کد خالص در محیطی به نام lstlisting وارد می‌شود. یعنی کد شما باید بین \begin{lstlisting} و \end{lstlisting} قرار گیرد.
  • به مانند حالت قبل، اگر می‌خواهید کد را در متن فارسی وارد کنید حتما آن بین یک محیط latin قرار دهید.
  • تنظیمات بسته listings در این روش به دو صورت انجام می شود:
  1. توسط دستور lstset. این دستور را باید قبل از محیط lstlisting وارد کنید. برای مثال ذکر شده خواهیم داشت.
  2. \begin{latin}
    \lstset{language=C}
    \begin{lstlisting}
    ......
    ......
    \end{lstlisting}
    \end{latin}

    شما می توانید دستور lstset‌ را قبل از \begin{document} نیز قرار دهید. تنظیمات lstset‌ تا زمانی که شما دوباره lstset‌ را بکار نبرید، پابرجا باقی خواهد ماند.

  3. به عنوان تنظیمات محیط lstlisting در داخل [] بعد از \begin{lstlisting}.
  4. \begin{latin}
    \begin{lstlisting}[language=C]
    ......
    ......
    \end{lstlisting}
    \end{latin}

تنظیمات

نحوه وارد کردن تنظیمات

همان طور که پیشتر ذکر شد، شما دو روش برای وارد کردن تنظیمات بسته listings دارید.

  • استفاده از دستور lstset.
  • وارد کردن به عنوان آرگومان دستورات وارد کردن کد.

در مثال زیر از هر دو شیوه استفاده شده است.

\begin{latin}
\lstset{emph={pMax,pMin,transP,waitingUser,waitQueue},emphstyle=\color{red},backgroundcolor=\color{codeColor},lineskip=.2cm}
\lstinputlisting[language=Java]{Code/threadQueue.java}
\end{latin}

با استفاده از دستور lstdefinestyle شما می‌توانید چندین استایل برای وارد کردن کد تعریف کنید و به فراخور کد از یکی از آن ها استفاده کنید. برای مثال در کد زیر دو نوع استایل تعریف شده است.

\lstdefinestyle{customc}{
  belowcaptionskip=1\baselineskip,
  breaklines=true,
  frame=L,
  xleftmargin=\parindent,
  language=C,
  showstringspaces=false,
  basicstyle=\footnotesize\ttfamily,
  keywordstyle=\bfseries\color{green!40!black},
  commentstyle=\itshape\color{purple!40!black},
  identifierstyle=\color{blue},
  stringstyle=\color{orange},
}
 
\lstdefinestyle{customasm}{
  belowcaptionskip=1\baselineskip,
  frame=L,
  xleftmargin=\parindent,
  language=[x86masm]Assembler,
  basicstyle=\footnotesize\ttfamily,
  commentstyle=\itshape\color{purple!40!black},
}

در نهایت می‌توانید در هر جایی که می‌خواهید کد خود را وارد کنید هر یک از استایل ها را فراخوانی کنید.

\begin{latin}
\lstinputlisting[style=customasm]{sched.s}
\end{latin}

مهم‌ترین تنظیمات

بسته listings‌ تنظیمات زیادی دارد. ما در این مجال به برخی از مهم‌ترین آن ها اشاره می‌کنیم.

  • language: زبانی برنامه‌ای که می‌خواهید وارد کنید. لیست کاملی از زبان‌های برنامه نویسی که listings‌ پشتیبانی می‌کند در پیوند LaTeX/Source Code Listings ارایه شده است.
  • emph: کلماتی که به عنوان emph در تنظیمات تعریف می شود، با استایل تعیین شده توسط emphstyle در کد وارد می شوند. به عنوان مثال کد زیر را در نظر بگیرید.
\begin{latin}
\lstset{emph={pMax,pMin,transP,waitingUser,waitQueue},emphstyle=\color{red}}
\lstinputlisting[language=Java]{threadQueue.java}
\end{latin}

در مثال فوق، در صورتی که کلمات pMax,pMin,transP,waitingUser,waitQueue در کد threadQueue.java یافت شوند، این کلمات به رنگ قرمز نمایش داده خواهد شد.

در محیط کد
  • numbers: که می‌تواند یکی از مقادیر none و left و right را به خود بگیرد. در صورتی که مقادیر left یا right را انتخاب کنید، خطوط برنامه شماره گذاری می‌شود و شماره ها در سمت چپ یا راست خواهد آمد.
  • numbersep: تعیین فاصله افقی شماره ها از کد
  • numberstyle: تعیین استایل شماره ها. مثلا numberstyle=\tiny\color{mygray} شماره ها به رنگ mygray و به اندازه tiny نمایش داده می شوند.
  • stepnumber: برای مثال اگر مقدار stepnumber=2 باشد، آن‌گاه یک خط در میان شماره گذاری انجام می‌شود.
  • lineskip: فاصله خطوط به مقدار lineskip از یکدیگر افزایش خواهد یافت.
  • backgroundcolor: رنگ پیش زمینه کادری که در آن کدها وارد می‌شوند.
  • basicstyle: اندازه کدها در متن. برای مثال: basicstyle=\footnotesize
  • commentstyle: استایل وارد کردن کامنت در کد. به عنوان مثال commentstyle=\color{mygreen} رنگ کامنت های وارد شده در کد را به رنگ mygreen تبدیل می کند.
  • showspaces: فاصله ها (space) در کد را با کاراکتری معین، تعیین می کند. مقدار این تنظیم می تواند true یا false باشد.
  • showtabs: tap ها را در متن مشخص می کند. مقدار این تنظیم می تواند true یا false باشد.
  • morekeywords: در هر زبان برنامه نویسی یکسری از واژه ها به عنوان keywordstyle آن زبان محسوب می شود. در بسته listings، morekeywords استاندارد هر زبان قرار داده شده است. شما می توانید به دلخواه خود یکسری keyword جدید به keyword‌های استاندارد اضافه کنید.
  • deletekeywords: کلمه‌ای که در این تنظیم مشخص می کنید از بین کلمات کلیدی زبان انتخاب شده حذف می شود. به عنوان مثال اگر شما زبان MATLAB را انتخاب کرده باشید، و deletekeywords={clear} باشد، آن‌گاه کلمه کلیدی clear از بین کلمات کلیدی MATLAB در وارد کردن کد به صورت موقت حذف می شود.
  • frame: اضافه کردن یک کادر بدور کد. این تنظیم می تواند یکی از مقادیر none|leftline|topline|bottomline|lines|single|shadowbox را داشته باشد. بسته Listings تنظیمات زیادی برای تنظیم کادر دور محیط کد فراهم آورده است که با مراجعه به راهنمای آن می توانید از آن ها استفاده کنید.

برخی نکات

وارد کردن روابط ریاضی در کد

فرض کنید که می خواهید در قسمت کامنت کدی که در متن وارد کرده اید، یک عبارت در mathmode داشته باشید. مثلا بنویسید \alpha + d_{i} . ولی می‌خواهید این عبارت به صوررت درست یعنی $\alpha + d_{i}$ در متن ظاهر شود. برای این کار کافی است که تنظیم texcl یا mathescape را فعال کنید.

\begin{latin}
\begin{lstlisting}[mathescape=true]
// calculate  $a_{ij}$
$a_{ij} = a_{jj}/a_{ij} + \alpha$;
\end{lstlisting}
\end{latin}

با اجرای Latex بر روی فایل tex، خروجی به صورت شکل روبه رو خواهد بود.

وارد کردن کد حاوی عبارت ریاضی